@mercury-fw/channel-http 0.10.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # @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
+
+- 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.
+
+- ebde9e2: The texts a person sees can be in their language. The core's own fixed texts (the refusal of someone the agent doesn't know, the account-linking replies, the login errors, the tool status lines, the terminal's own lines) are English, each under a key (`core.access.unknown`, …), and an app adds a language with a file of its own: `i18n: { defaultLocale, locales: { it } }` in `mercury.config.ts`, each file mapping keys to texts. A person picks their language by asking the agent, which saves it with `set_preferred_language` (only the languages the app ships; not offered when it ships English alone) and answers in it from then on. Whoever hasn't picked one gets `defaultLocale`, then English. A key a language's file lacks shows as the key itself, and the log names the missing keys at startup. `GET /me` on the HTTP channel also says the caller's language.
+
+  The texts that were in Italian (tool status lines, the terminal's lines) are now English by default, and the language is no longer one of the facts inferred from conversations.
+
+  An existing app keeps working, with these changes:
+
+  1. `access.unknownMessage` is gone. To keep a custom refusal, put it in `locales/en.json` as `{ "core.access.unknown": "…" }`, and in `mercury.config.ts` import it (`import en from "./locales/en.json";`) and set `i18n: { locales: { en } }`.
+  2. To keep the status and terminal lines in Italian, add `locales/it.json` with the `core.` keys translated (start it as `{}`: the log lists the missing keys at startup), and in `mercury.config.ts` import it (`import it from "./locales/it.json";`) and set `i18n: { defaultLocale: "it", locales: { it } }` (`locales: { en, it }` when you did step 1 too).
+  3. Whenever the config imports a file from `locales/` (steps 1 and 2), the image needs the folder: add `COPY --chown=mercury:mercury locales ./locales` after the `mercury.config.ts` line of the `Dockerfile`, or the app fails at startup.
+  4. For the terminal (`mfw repl`) to follow the language too, add `texts: app.texts,` to `createTerminalProvider({ … })` in `src/repl.ts`; without it the terminal's own lines stay English.
+
+### 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.10.1
 
 ### Patch Changes

package/README.md

@@ -2,6 +2,8 @@
 
 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. `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
 ```
@@ -52,6 +54,10 @@ Runs one conversational turn; the reply streams back as Server-Sent Events.
 
 **Responses**: `200 text/event-stream` (the events below); `400` if `text` is missing, an opening has no `conversationId`, the body isn't JSON, or `conversationId` has other characters than the ones above.
 
+**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>`:
@@ -63,9 +69,9 @@ Reasoning and answer text arrive as **incremental deltas** — never one finishe
 | `tool` | `{ label, detail, toolCallId, name }` | a tool call starts; `name` is the tool the model called, absent when Mercury is saving something to memory |
 | `tool_finish` | `{ toolCallId, outcome }` | a tool call settles (`outcome`: `success` \| `failed` \| `pending`) |
 | `text` | `{ chunk }` | an answer-text delta |
-| `pending` | `{ command, token, choices }` | a confirm-required action was staged; send a token back to confirm it — as a later `/turn` `text`, or via `POST /confirm`. `choices` is every way to answer (`{ token, label }`, in order; one, labelled `Conferma`, for a plain staging): the others die with the one sent |
+| `pending` | `{ command, token, choices }` | a confirm-required action was staged; send a token back to confirm it — as a later `/turn` `text`, or via `POST /confirm`. `choices` is every way to answer (`{ token, label }`, in order, each label in the caller's language; one with an empty `label` for a plain staging, which the UI words itself, a "Confirm" button): the others die with the one sent |
 | `login` | `{ service, url }` | the caller isn't logged in to `service` yet, which a plugin acts on as them: show them `url` to open (the model never gets it) |
-| `final` | `{ text }` | the complete answer (also emitted for a token confirmation, with no model turn) |
+| `final` | `{ text, pendingNote? }` | the complete answer (also emitted for a token confirmation, with no model turn). `pendingNote` is there when the model wrote nothing because the turn staged an action: the core's stand-in sentence `text` begins with (then any list the turn surfaced). A UI showing its own confirmation hides it; the conversation's transcript keeps it |
 | `error` | `{ message }` | the turn failed mid-stream |
 
 ```bash
@@ -77,7 +83,7 @@ curl -N -X POST http://localhost:4100/turn \
 
 ## `GET /login/callback`
 
-Where a person comes back after logging in to a service a plugin acts on as them (Jira, Bitbucket): the `login` event's `url` sends them to the service, and the service sends their browser here with `code` and `state`. Mounted only with `HTTP_SURFACE_PUBLIC_URL`, at `<HTTP_SURFACE_PUBLIC_URL>/login/callback`, which is the URL to register as a callback on the service's app (the Atlassian 3LO app, the Bitbucket consumer people log in through). No bearer token: the browser has none here, and the `state` Mercury issued for that person, single-use and valid for ten minutes, is what ties the request to their login. Answers with a plain-text page saying how it went.
+Where a person comes back after logging in to a service a plugin acts on as them (Jira, Bitbucket): the `login` event's `url` sends them to the service, and the service sends their browser here with `code` and `state`. Mounted only with `HTTP_SURFACE_PUBLIC_URL`, at `<HTTP_SURFACE_PUBLIC_URL>/login/callback`, which is the URL to register as a callback on the service's app (the Atlassian 3LO app, the Bitbucket consumer people log in through). No bearer token: the browser has none here, and the `state` Mercury issued for that person, single-use and valid for ten minutes, is what ties the request to their login. Answers with a plain-text page saying how it went, in the language the browser asks for (`Accept-Language`), else the app's default; a login that failed reads in the language of the person who started it.
 
 Whoever opens the link and accepts decides which account gets linked: a link belongs to the person it was shown to, and someone else accepting it would link their own account to that person's Mercury identity. A UI should say so next to the link. Checking the linked account against the person is [#179](https://github.com/lucabro81/mercury-fw/issues/179).
 
@@ -85,9 +91,13 @@ 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, `{ 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.
+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.
 
 ## Read-only introspection
 
@@ -99,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 }` — how you asked the assistant to call you, `null` when you never said; not 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, 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,10 +34,14 @@ 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. */
     assistantName?: string;
+    /** The texts in each caller's language (`ctx.i18n`). */
+    i18n?: ChannelI18n;
 };
 export declare function createHttpProvider(deps: HttpProviderDeps): Provider & {
     stop(): Promise<void>;

package/dist/http-server.d.ts

@@ -22,13 +22,13 @@
  * Confirm resolution is injected too (`confirm`/`resolveConfirmation`), so this
  * package never imports the app.
  */
-import { type HandleTurn, type Authenticate, type ChannelHostReads, type ConfirmOutcome, type LoginOutcome, type Principal, type Admission, type ChannelLinking } from "@mercury-fw/channel-types";
-/** Resolves a bare confirmation token to a reply string, or `null` if the input isn't a token. Injected by the core (`ctx.confirm`). */
-export type ConfirmFn = (token: string, sessionKey: string, principal: Principal) => Promise<string | null>;
+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`). */
-export type ResolveConfirmationFn = (token: string, sessionKey: string, principal: Principal) => Promise<ConfirmOutcome>;
+export type ResolveConfirmationFn = NonNullable<ChannelRuntimeContext["resolveConfirmation"]>;
 /** Whether the core talks to an authenticated caller at all, injected by the core (`ctx.admit`); everyone when absent. */
-export type AdmitFn = (principal: Principal) => Promise<Admission>;
+export type AdmitFn = (principal: Principal, hint?: string) => Promise<Admission>;
 export type TurnRequestDeps = {
     handleTurn: HandleTurn;
     /** Who is calling, injected from the app's auth provider; `null` = refused. */
@@ -36,6 +36,8 @@ export type TurnRequestDeps = {
     admit?: AdmitFn;
     /** Bare-token interception before the model, injected by the core. */
     confirm: ConfirmFn;
+    /** The texts in the caller's language, injected by the core (`ctx.i18n`): what `Content-Language` says. */
+    i18n?: ChannelI18n;
     /** Allowed CORS origin echoed back to a browser UI; defaults to `*`. */
     corsOrigin?: string;
     /** Test seam for the ephemeral session key when the client sends no conversationId. */
@@ -74,6 +76,8 @@ export type ConfirmRequestDeps = {
     admit?: AdmitFn;
     resolveConfirmation: ResolveConfirmationFn;
     corsOrigin?: string;
+    /** The texts in the caller's language, injected by the core: what `Content-Language` says. */
+    i18n?: ChannelI18n;
 };
 /**
  * `POST /confirm { token, conversationId }` — the explicit confirmation
@@ -83,7 +87,8 @@ export type ConfirmRequestDeps = {
  * keyed on the caller's own session (`<principal.id>:<conversationId>`), so a
  * token staged in someone else's conversation is never found. `resolved: true` means the token matched a
  * pending confirmation and its staged action was consumed and run; the `text`
- * then reports whether that execution succeeded. `resolved: false` means the
+ * (the core's, in the caller's language) then reports whether that execution
+ * succeeded. `resolved: false` means the
  * token was not a pending confirmation (unknown, expired, already used, or not
  * even token-shaped). `resume: true` (with no `text`) means the action handed
  * its result back to the model: the client hears its answer by opening
@@ -117,10 +122,13 @@ export type CompleteLoginFn = (state: string, code: string) => Promise<LoginOutc
 export declare function handleLoginCallback(req: Request, deps: {
     complete: CompleteLoginFn;
     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;
 };
 /**
@@ -132,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;
@@ -144,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/dist/messages.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The HTTP channel's texts a person sees, in English: the base every
+ * instance's language files translate (`ChannelPlugin.messages`). Only the
+ * login page: everything else the surface sends is the core's, or the
+ * developer-facing errors of its API, which aren't translated.
+ */
+import type { Messages, Translate } from "@mercury-fw/channel-types";
+export declare const HTTP_MESSAGES: Messages;
+/** These texts in English, for a server built without the core's (`ChannelI18n`), as tests build it. */
+export declare const englishHttp: Translate;

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, 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,10 +31,14 @@ 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. */
   assistantName?: string;
+  /** The texts in each caller's language (`ctx.i18n`). */
+  i18n?: ChannelI18n;
 };
 
 export function createHttpProvider(deps: HttpProviderDeps): Provider & { stop(): Promise<void> } {
@@ -52,8 +56,10 @@ 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 }),
       });
       deps.logins?.accept(deps.logins.callbackUrl);
     },

package/http-server.ts

@@ -25,18 +25,19 @@
 import {
   detectLoginRequired,
   detectPendingConfirmation,
-  PENDING_CONFIRMATION_NOTE,
-  RESUME_AFTER_CONFIRM,
   type HandleTurn,
   type TurnSink,
   type Authenticate,
   type ChannelHostReads,
-  type ConfirmOutcome,
+  type ChannelI18n,
+  type ChannelRuntimeContext,
   type LoginOutcome,
   type Principal,
   type Admission,
   type ChannelLinking,
+  type ChannelSettings,
 } from "@mercury-fw/channel-types";
+import { englishHttp } from "./messages.ts";
 
 /**
  * A client's conversation id becomes part of the session key and the log
@@ -51,13 +52,30 @@ function forLog(text: string): string {
   return text.replace(/[\u0000-\u001f\u007f]/g, "?");
 }
 
-/** Resolves a bare confirmation token to a reply string, or `null` if the input isn't a token. Injected by the core (`ctx.confirm`). */
-export type ConfirmFn = (token: string, sessionKey: string, principal: Principal) => Promise<string | null>;
+/** 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`). */
-export type ResolveConfirmationFn = (token: string, sessionKey: string, principal: Principal) => Promise<ConfirmOutcome>;
+export type ResolveConfirmationFn = NonNullable<ChannelRuntimeContext["resolveConfirmation"]>;
 
 /** Whether the core talks to an authenticated caller at all, injected by the core (`ctx.admit`); everyone when absent. */
-export type AdmitFn = (principal: Principal) => Promise<Admission>;
+export type AdmitFn = (principal: Principal, hint?: string) => Promise<Admission>;
+
+/** The language the caller's client asks for (`Accept-Language`), when it says. */
+function languageHint(req: Request): string | undefined {
+  const value = req.headers.get("accept-language")?.trim();
+  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 } : {};
+}
 
 export type TurnRequestDeps = {
   handleTurn: HandleTurn;
@@ -66,6 +84,8 @@ export type TurnRequestDeps = {
   admit?: AdmitFn;
   /** Bare-token interception before the model, injected by the core. */
   confirm: ConfirmFn;
+  /** The texts in the caller's language, injected by the core (`ctx.i18n`): what `Content-Language` says. */
+  i18n?: ChannelI18n;
   /** Allowed CORS origin echoed back to a browser UI; defaults to `*`. */
   corsOrigin?: string;
   /** Test seam for the ephemeral session key when the client sends no conversationId. */
@@ -91,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",
+    "access-control-allow-methods": "GET, POST, PATCH, OPTIONS",
+    "access-control-allow-headers": "content-type, authorization, accept-language, x-time-zone",
   };
 }
 
@@ -104,20 +124,26 @@ function unauthorized(origin: string): Response {
   );
 }
 
-/** The core's refusal of an authenticated caller: 403 for someone it doesn't know, 503 when it couldn't tell, with what to tell them. */
-function notAdmitted(admission: Exclude<Admission, { ok: true }>, origin: string): Response {
+/** The core's refusal of an authenticated caller: 403 for someone it doesn't know, 503 when it couldn't tell, with what to tell them, in the language they asked for. */
+function notAdmitted(admission: Exclude<Admission, { ok: true }>, origin: string, language: Record<string, string>): Response {
   return Response.json(
     { ok: false, error: admission.message, reason: admission.reason },
-    { status: admission.reason === "unknown" ? 403 : 503, headers: corsHeaders(origin) },
+    { status: admission.reason === "unknown" ? 403 : 503, headers: { ...corsHeaders(origin), ...language } },
   );
 }
 
 /** The caller of `req`, authenticated and admitted, or the response refusing them. */
-async function caller(req: Request, deps: { authenticate: Authenticate; admit?: AdmitFn }, origin: string): Promise<Principal | Response> {
+async function caller(
+  req: Request,
+  deps: { authenticate: Authenticate; admit?: AdmitFn; i18n?: ChannelI18n },
+  origin: string,
+): Promise<Principal | Response> {
   const principal = await deps.authenticate(req);
   if (principal === null) return unauthorized(origin);
-  const admission = deps.admit ? await deps.admit(principal) : { ok: true as const };
-  return admission.ok ? principal : notAdmitted(admission, origin);
+  const hint = languageHint(req);
+  const admission = deps.admit ? await deps.admit(principal, hint) : { ok: true as const };
+  // A refused caller is nobody the core knows: their client's language, else the default.
+  return admission.ok ? principal : notAdmitted(admission, origin, await contentLanguage(deps.i18n, null, hint));
 }
 
 /** 204 preflight response for an `OPTIONS` request, carrying only CORS headers. */
@@ -187,6 +213,9 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
     return Response.json({ ok: false, error: "invalid conversationId" }, { status: 400, headers: cors });
   }
   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
   // the in-flight turn stops instead of running to completion — the "stop"
@@ -215,21 +244,19 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
 
       // Same deterministic interception as every other channel — a
       // previously-approved mutation must never depend on the model.
-      const confirmReply = opening || resume ? null : await deps.confirm(text, sessionKey, principal);
-      if (confirmReply !== null && confirmReply !== RESUME_AFTER_CONFIRM) {
-        send("final", { text: confirmReply });
+      const reply = opening || resume ? null : await deps.confirm(text, sessionKey, principal, hint);
+      if (reply !== null && !reply.resume) {
+        send("final", { text: reply.text });
         close();
         return;
       }
       // The confirmed action's result goes back to the model: the turn runs again, on this stream.
-      const resuming = resume || confirmReply === RESUME_AFTER_CONFIRM;
+      const resuming = resume || reply?.resume === true;
 
       const sink: TurnSink = {
         onToolStart: (label, detail, toolCallId, toolName) => send("tool", { label, detail, toolCallId, name: toolName }),
         onToolFinish: (toolCallId, outcome) => send("tool_finish", { toolCallId, outcome }),
-        onTextChunk: (chunk) => {
-          if (chunk !== PENDING_CONFIRMATION_NOTE) send("text", { chunk });
-        },
+        onTextChunk: (chunk) => send("text", { chunk }),
         onReasoningChunk: (chunk, id) => send("reasoning", { chunk, id }),
         onReasoningEnd: (id, failed) => send("reasoning_end", { id, failed }),
         onStep: (step) => {
@@ -239,7 +266,10 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
           if (login) send("login", { service: login.service, url: login.url });
         },
         onUsage: () => {},
-        finalize: async (finalText) => send("final", { text: finalText }),
+        // The core says when the text is its stand-in for an answer the
+        // model didn't write: a UI showing its own confirmation hides it.
+        finalize: async (finalText, info) =>
+          send("final", info?.pendingNote === undefined ? { text: finalText } : { text: finalText, pendingNote: info.pendingNote }),
         dispose: () => {},
       };
 
@@ -257,6 +287,8 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
             ...(named ? { resume: deps.resumeMaxChars === undefined ? {} : { maxChars: deps.resumeMaxChars } } : {}),
             ...(opening ? { opening: true as const } : {}),
             ...(resuming ? { resumeAfterConfirm: true as const } : {}),
+            ...(hint === undefined ? {} : { languageHint: hint }),
+            ...(zone === undefined ? {} : { timeZoneHint: zone }),
           },
           sink,
         );
@@ -276,7 +308,7 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
     },
   });
 
-  return new Response(stream, { headers: { ...SSE_HEADERS, ...cors } });
+  return new Response(stream, { headers: { ...SSE_HEADERS, ...cors, ...language } });
 }
 
 export type ConfirmRequestDeps = {
@@ -284,6 +316,8 @@ export type ConfirmRequestDeps = {
   admit?: AdmitFn;
   resolveConfirmation: ResolveConfirmationFn;
   corsOrigin?: string;
+  /** The texts in the caller's language, injected by the core: what `Content-Language` says. */
+  i18n?: ChannelI18n;
 };
 
 /**
@@ -294,7 +328,8 @@ export type ConfirmRequestDeps = {
  * keyed on the caller's own session (`<principal.id>:<conversationId>`), so a
  * token staged in someone else's conversation is never found. `resolved: true` means the token matched a
  * pending confirmation and its staged action was consumed and run; the `text`
- * then reports whether that execution succeeded. `resolved: false` means the
+ * (the core's, in the caller's language) then reports whether that execution
+ * succeeded. `resolved: false` means the
  * token was not a pending confirmation (unknown, expired, already used, or not
  * even token-shaped). `resume: true` (with no `text`) means the action handed
  * its result back to the model: the client hears its answer by opening
@@ -319,18 +354,19 @@ export async function handleConfirmRequest(req: Request, deps: ConfirmRequestDep
   if (!CONVERSATION_ID.test(conversationId)) {
     return Response.json({ ok: false, error: "invalid conversationId" }, { status: 400, headers: cors });
   }
-  const outcome = await deps.resolveConfirmation(token, `${principal.id}:${conversationId}`, principal);
+  const hint = languageHint(req);
+  const headers = { ...cors, ...(await contentLanguage(deps.i18n, principal, hint)) };
+  const outcome = await deps.resolveConfirmation(token, `${principal.id}:${conversationId}`, principal, hint);
   switch (outcome.status) {
     case "not-a-token":
     case "not-found":
-      return Response.json({ ok: true, resolved: false }, { headers: cors });
+      return Response.json({ ok: true, resolved: false }, { headers });
     case "ok":
-      return Response.json({ ok: true, resolved: true, text: `Confermato ed eseguito: ${JSON.stringify(outcome.data)}` }, { headers: cors });
     case "failed":
-      return Response.json({ ok: true, resolved: true, text: `Confermato, ma l'esecuzione è fallita: ${outcome.error}` }, { headers: cors });
+      return Response.json({ ok: true, resolved: true, text: outcome.text }, { headers });
     case "resume":
       // The result went back to the model: the client opens `/turn { resume: true }` to hear its answer.
-      return Response.json({ ok: true, resolved: true, resume: true }, { headers: cors });
+      return Response.json({ ok: true, resolved: true, resume: true }, { headers });
   }
 }
 
@@ -365,11 +401,11 @@ function linkRoutes(deps: LinkRequestDeps): Record<string, { POST: (req: Request
 export type CompleteLoginFn = (state: string, code: string) => Promise<LoginOutcome>;
 
 /** A plain-text page for the person's browser, at the end of their login. */
-function loginPage(text: string, status: number): Response {
+function loginPage(text: string, status: number, language: Record<string, string> = {}): Response {
   // The URL carried the code and the state: neither kept nor passed on.
   return new Response(text, {
     status,
-    headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store", "referrer-policy": "no-referrer" },
+    headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store", "referrer-policy": "no-referrer", ...language },
   });
 }
 
@@ -383,39 +419,50 @@ function loginPage(text: string, status: number): Response {
  */
 export async function handleLoginCallback(
   req: Request,
-  deps: { complete: CompleteLoginFn; assistantName?: string },
+  deps: { complete: CompleteLoginFn; assistantName?: string; i18n?: ChannelI18n },
 ): Promise<Response> {
   const assistant = deps.assistantName ?? "Mercury";
+  // Nobody is known on this page: the browser's language, then the default.
+  const texts = deps.i18n ? await deps.i18n.forRequest(null, languageHint(req)) : undefined;
+  const t = texts?.t ?? englishHttp;
+  const language: Record<string, string> = texts ? { "content-language": texts.locale } : {};
   const params = new URL(req.url).searchParams;
   const error = params.get("error");
   if (error !== null) {
     const reason = error.replace(/[^A-Za-z0-9_.-]/g, "").slice(0, 64);
-    return loginPage(`The login didn't happen (${reason}). Ask ${assistant} again for a new link.`, 400);
+    return loginPage(t("http.login.denied", { reason, assistant }), 400, language);
   }
   const code = params.get("code");
   const state = params.get("state");
-  if (!code || !state) return loginPage(`The login link came back without a code or a state. Ask ${assistant} again for a new link.`, 400);
+  if (!code || !state) return loginPage(t("http.login.incomplete", { assistant }), 400, language);
   const outcome = await deps.complete(state, code);
-  return outcome.ok
-    ? loginPage(`You're logged in to ${outcome.service}. Go back to the conversation and ask again.`, 200)
-    : loginPage(outcome.error, 400);
+  // A failed login's text is the core's, in the language of whoever started it: no header claims otherwise.
+  return outcome.ok ? loginPage(t("http.login.done", { service: outcome.service }), 200, language) : loginPage(outcome.error, 400);
 }
 
 /** The login callback route, mounted when the server can complete logins. */
 function loginRoutes(
   complete: CompleteLoginFn,
   assistantName: string | undefined,
+  i18n: ChannelI18n | undefined,
 ): Record<string, { GET: (req: Request) => Promise<Response> }> {
   return {
     "/login/callback": {
-      GET: (req) => handleLoginCallback(req, { complete, ...(assistantName === undefined ? {} : { assistantName }) }),
+      GET: (req) =>
+        handleLoginCallback(req, {
+          complete,
+          ...(assistantName === undefined ? {} : { assistantName }),
+          ...(i18n === undefined ? {} : { i18n }),
+        }),
     },
   };
 }
 
-/** 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;
 };
 
@@ -428,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 =>
@@ -479,11 +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 } | null;
-            return json({ ok: true, name: me?.name ?? null });
-          }),
+          "/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) })),
@@ -519,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;
 };
@@ -547,12 +618,13 @@ export function startHttpServer(deps: HttpServerDeps): ReturnType<typeof Bun.ser
             ...(deps.admit === undefined ? {} : { admit: deps.admit }),
             resolveConfirmation: deps.resolveConfirmation,
             corsOrigin: origin,
+            ...(deps.i18n === undefined ? {} : { i18n: deps.i18n }),
           }),
         OPTIONS: () => preflight(origin),
       },
       "/openapi.yaml": { GET: () => openApiResponse(origin), OPTIONS: () => preflight(origin) },
-      ...(deps.reads ? readRoutes(deps.reads, deps.authenticate, origin, deps.admit) : {}),
-      ...(deps.completeLogin ? loginRoutes(deps.completeLogin, deps.assistantName) : {}),
+      ...(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 }) : {}),
     },
     error: (err) =>

package/index.ts

@@ -16,14 +16,16 @@
  */
 import type { ChannelPlugin } from "@mercury-fw/channel-types";
 import { createHttpProvider } from "./http-provider.ts";
+import { HTTP_MESSAGES } from "./messages.ts";
 
 export { createHttpProvider, type HttpProviderDeps } from "./http-provider.ts";
 
 export const httpChannel: 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: "http",
+  messages: HTTP_MESSAGES,
   build: (ctx) => {
     if (!ctx.resolveConfirmation || !ctx.reads) {
       throw new Error("http channel requires the resolveConfirmation and reads capabilities on the runtime context");
@@ -44,7 +46,9 @@ export const httpChannel: ChannelPlugin = {
       reads: ctx.reads,
       authenticate: ctx.authenticate,
       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/messages.ts

@@ -0,0 +1,20 @@
+/**
+ * The HTTP channel's texts a person sees, in English: the base every
+ * instance's language files translate (`ChannelPlugin.messages`). Only the
+ * login page: everything else the surface sends is the core's, or the
+ * developer-facing errors of its API, which aren't translated.
+ */
+import type { Messages, Translate } from "@mercury-fw/channel-types";
+
+export const HTTP_MESSAGES: Messages = {
+  // The page a person lands on after logging in to a service (`GET /login/callback`).
+  "http.login.denied": "The login didn't happen ({reason}). Ask {assistant} again for a new link.",
+  "http.login.incomplete": "The login link came back without a code or a state. Ask {assistant} again for a new link.",
+  "http.login.done": "You're logged in to {service}. Go back to the conversation and ask again.",
+};
+
+/** These texts in English, for a server built without the core's (`ChannelI18n`), as tests build it. */
+export const englishHttp: Translate = (key, params) =>
+  (HTTP_MESSAGES[key] ?? key).replace(/\{(\w+)\}/g, (whole, name: string) =>
+    params !== undefined && Object.hasOwn(params, name) ? String(params[name]) : whole,
+  );

package/openapi.yaml

@@ -101,7 +101,15 @@ paths:
         speaks first in the conversation named (right after someone signs
         in): it does only for someone it doesn't know the name of, asking how
         to call them, and otherwise the stream carries a single `final` with
-        an empty text.
+        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. 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:
@@ -125,6 +133,9 @@ paths:
             service the caller has to log in to first, with the link to open),
             `final` (the
             authoritative complete answer), and `error`.
+          headers:
+            Content-Language:
+              $ref: "#/components/headers/ContentLanguage"
           content:
             text/event-stream:
               schema:
@@ -141,7 +152,10 @@ paths:
       description: >
         Runs a one-time confirmation token through the same mechanism the
         bare-token-in-`text` path uses, keyed on the caller's own conversation
-        (`<caller id>:<conversationId>`). Never touches the model.
+        (`<caller id>:<conversationId>`). Never touches the model. The reply
+        is in the caller's language, as on `/turn`.
+      parameters:
+        - $ref: "#/components/parameters/AcceptLanguage"
       requestBody:
         required: true
         content:
@@ -162,6 +176,9 @@ paths:
             already used). `resolved: true` with `resume: true` and no `text`
             when the action handed its result back to the model: the answer
             comes from `POST /turn { resume: true, conversationId }`.
+          headers:
+            Content-Language:
+              $ref: "#/components/headers/ContentLanguage"
           content:
             application/json:
               schema:
@@ -329,8 +346,10 @@ paths:
       summary: Who the caller is to the assistant
       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. Not there on an
-        older core, which can't say.
+        asks for an opening turn after a sign-in only then. Also the language
+        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"
@@ -339,7 +358,7 @@ paths:
         "503":
           $ref: "#/components/responses/NotAdmitted"
         "200":
-          description: The caller's name, or null.
+          description: The caller's name, language and time zone, or null.
           content:
             application/json:
               schema:
@@ -350,6 +369,55 @@ paths:
                     type: boolean
                   name:
                     type: [string, "null"]
+                  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
@@ -493,20 +561,31 @@ paths:
         Mounted when `HTTP_SURFACE_PUBLIC_URL` is set. The service sends the
         person's browser here with `code` and `state` (or `error`); the
         single-use state is the credential, so no bearer token is needed.
-        Answers with a plain-text page.
+        Answers with a plain-text page, in the language the browser asks for
+        (`Accept-Language`), else the instance's default; a failed login reads
+        in the language of the person who started it.
       security: []
       parameters:
+        - $ref: "#/components/parameters/AcceptLanguage"
         - { name: code, in: query, schema: { type: string } }
         - { name: state, in: query, schema: { type: string } }
         - { name: error, in: query, schema: { type: string } }
       responses:
         "200":
           description: Logged in.
+          headers:
+            Content-Language:
+              $ref: "#/components/headers/ContentLanguage"
           content:
             text/plain:
               schema: { type: string }
         "400":
           description: Refused, expired, already used, or missing code/state.
+          headers:
+            Content-Language:
+              description: Set on a denied or incomplete login (the browser's language); not on a failed one, which reads in the language of whoever started it.
+              schema:
+                type: string
           content:
             text/plain:
               schema: { type: string }
@@ -522,6 +601,37 @@ paths:
               schema:
                 type: string
 components:
+  parameters:
+    AcceptLanguage:
+      name: Accept-Language
+      in: header
+      required: false
+      description: >
+        The languages the client prefers, as browsers send them
+        (`it-IT,it;q=0.9,en;q=0.8`). Used for the texts the person reads when
+        they saved no language of their own; a language the instance doesn't
+        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: >
+        The language of the caller's texts as it stood when the response
+        started, one the instance ships (`en`, `it`); a person who picks
+        another language during a turn gets it from the next one.
+      schema:
+        type: string
   securitySchemes:
     bearerAuth:
       type: http
@@ -545,7 +655,11 @@ components:
       description: >
         An authenticated caller the core won't talk to: `403` when the app's
         directory doesn't know them, `503` when it can't be reached. Nothing
-        behind the route runs.
+        behind the route runs. `error` is in the language `Accept-Language`
+        asks for, which `Content-Language` names.
+      headers:
+        Content-Language:
+          $ref: "#/components/headers/ContentLanguage"
       content:
         application/json:
           schema:
@@ -616,7 +730,7 @@ components:
           description: On `pending` — the one-time confirmation token (the first choice's).
         choices:
           type: array
-          description: On `pending` — every way to answer, in order; a plain staging has one, labelled `Conferma`.
+          description: On `pending` — every way to answer, in order, each label in the caller's language; a plain staging has one with an empty label, which the UI words itself (a "Confirm" button).
           items:
             type: object
             required: [token, label]
@@ -634,6 +748,13 @@ components:
         text:
           type: string
           description: On `final` — the authoritative complete answer.
+        pendingNote:
+          type: string
+          description: >
+            On `final`, when the model wrote nothing because the turn staged an
+            action: the stand-in sentence `text` begins with (followed by any
+            list the turn surfaced). A UI showing its own confirmation hides
+            it; the conversation's transcript keeps it.
         message:
           type: string
           description: On `error` — the failure message.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/channel-http",
-  "version": "0.10.1",
+  "version": "0.12.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -18,11 +18,11 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@mercury-fw/channel-types": ">=0.51.0 <1.0.0"
+    "@mercury-fw/channel-types": ">=0.54.0 <1.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-types": "0.52.0",
-    "@mercury-fw/plugin-types": "0.52.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"