@mercury-fw/channel-http 0.10.1 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @mercury-fw/channel-http
 
+## 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.
+
 ```bash
 bun add @mercury-fw/channel-http
 ```
@@ -52,6 +54,8 @@ 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).
+
 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 +67,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 +81,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).
 
@@ -87,7 +91,7 @@ A code for linking another of the caller's accounts to them, for the UI to show:
 
 ## `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 +103,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 }` — 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 /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 } from "@mercury-fw/channel-types";
 export type HttpProviderDeps = {
     port: number;
     /** Bare-token interception before the model. */
@@ -38,6 +38,8 @@ export type HttpProviderDeps = {
     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 } 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,6 +122,7 @@ 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. */
 type ReadRoute = {

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 } from "@mercury-fw/channel-types";
 
 export type HttpProviderDeps = {
   port: number;
@@ -35,6 +35,8 @@ export type HttpProviderDeps = {
   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> } {
@@ -54,6 +56,7 @@ export function createHttpProvider(deps: HttpProviderDeps): Provider & { stop():
         ...(deps.linking === undefined ? {} : { linking: deps.linking }),
         ...(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,18 @@
 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,
 } 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 +51,24 @@ 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;
+}
+
+/** `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 +77,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. */
@@ -92,7 +105,7 @@ 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-headers": "content-type, authorization, accept-language",
   };
 }
 
@@ -104,20 +117,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 +206,8 @@ 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 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 +236,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 +258,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 +279,7 @@ 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 }),
           },
           sink,
         );
@@ -276,7 +299,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 +307,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 +319,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 +345,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 +392,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,32 +410,41 @@ 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 }),
+        }),
     },
   };
 }
@@ -481,8 +517,9 @@ export function readRoutes(
       : {
           "/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 });
+            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 }) });
           }),
         }),
     "/health": route(async () => json({ ok: true, ...(await reads.health() as object) })),
@@ -547,12 +584,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.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,6 +46,7 @@ export const httpChannel: ChannelPlugin = {
       reads: ctx.reads,
       authenticate: ctx.authenticate,
       admit: ctx.admit,
+      i18n: ctx.i18n,
       ...(ctx.linking === undefined ? {} : { linking: ctx.linking }),
       ...(resumeMaxChars === undefined ? {} : { resumeMaxChars }),
       ...(ctx.assistantName === undefined ? {} : { assistantName: ctx.assistantName }),

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,12 @@ 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.
+      parameters:
+        - $ref: "#/components/parameters/AcceptLanguage"
       requestBody:
         required: true
         content:
@@ -125,6 +130,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 +149,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 +173,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 +343,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, `null` when they never said (missing
+        when the core doesn't know languages). Not there on an older core,
+        which can't say.
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
@@ -339,7 +355,7 @@ paths:
         "503":
           $ref: "#/components/responses/NotAdmitted"
         "200":
-          description: The caller's name, or null.
+          description: The caller's name and language, or null.
           content:
             application/json:
               schema:
@@ -350,6 +366,9 @@ 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.
   /tool-log:
     get:
       summary: The tool calls made in the caller's recent turns
@@ -493,20 +512,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 +552,26 @@ 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
+  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 +595,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 +670,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 +688,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.11.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.54.0",
+    "@mercury-fw/plugin-types": "0.54.0",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"