@mercury-fw/channel-http 0.8.3 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @mercury-fw/channel-http
 
+## 0.9.0
+
+### Minor Changes
+
+- b7438a6: - The assistant remembers how each person wants to be called: they say it in conversation and the model saves it with the new `set_preferred_name` tool. It's a setting kept in `.mercury/profiles.json` on the vault's volume, not a wiki note, and every one-to-one turn tells the model the name.
+  - A turn can be an opening (`opening: true`, with no text): the assistant speaks first, but only to someone whose name it doesn't know, introducing itself and asking how to call them. For anyone else, and in a shared space, it says nothing and keeps nothing.
+  - `ChannelHostReads.me` says how the caller asked to be called, or `null`.
+  - HTTP: `POST /turn` takes `{ opening: true, conversationId }`, and `GET /me` answers `{ name }`. A UI asks for an opening right after a sign-in, when the name is `null`. The channel now needs channel-types 0.49.0 or later.
+
+## 0.8.4
+
+### Patch Changes
+
+- 62bb3a3: - `persona.name` is the assistant's name, Mercury when left out. A name that's blank, longer than 40 characters or on more than one line stops the app at startup.
+  - Every text the model reads refers to the name as `{{assistant}}`, and the core puts the persona's name there: the persona's identity and tone, the system prompt, plugin fragments, skills and tool descriptions. The model no longer takes "Mercury" for its own name when the app calls its assistant something else.
+  - Where the one acting is the system around the model, the texts say "the system" or "this instance" instead of Mercury: the wiki tools, the cli-engine's errors, the jira skill and its issue lists.
+  - Plugins get `assistantName` in their `build()` context, and channels in their runtime context, for texts they build while running. The login messages, the linking reply and the HTTP login page name the assistant that way.
+  - The tools a person runs as the assistant itself are `<tool>AsSelf`, previously `<tool>AsMercury`. The `mercury.act-as-self` roles are unchanged.
+  - `mfw create` writes the assistant's name as `persona.name`, with `persona/identity.md` and `persona/tone.md` referring to it. An existing app keeps working as it is: to rename its assistant everywhere, add `name` to its persona and write `{{assistant}}` in its persona files.
+
 ## 0.8.3
 
 ### Patch Changes

package/README.md

@@ -45,10 +45,11 @@ Runs one conversational turn; the reply streams back as Server-Sent Events.
 
 | field | type | required | description |
 |---|---|---|---|
-| `text` | string | yes | The user message. A bare confirmation token here confirms a staged action (see the `pending` event) without invoking the model. |
+| `text` | string | yes, unless `opening` | The user message. A bare confirmation token here confirms a staged action (see the `pending` event) without invoking the model. |
+| `opening` | `true` | no | The assistant speaks first, before the person writes anything: what a UI asks right after someone signs in, when `GET /me` says the assistant doesn't know their name. It introduces itself and asks how to call them, and saves the answer once they give it. For someone it already knows, the stream is a single `final` with an empty text. Needs `conversationId`; `text` is ignored. |
 | `conversationId` | string | no | Opaque, client-owned id that continues one of your conversations: letters, digits, `-` and `_`, up to 128 characters (a UUID fits) once surrounding whitespace is trimmed, `400` otherwise. Sent again, however long after, it continues that conversation, rebuilt from the archive if Mercury had freed it (see `HTTP_SURFACE_RESUME_MAX_CHARS`). Omitted ⇒ a fresh one-off session that can't be continued. |
 
-**Responses**: `200 text/event-stream` (the events below); `400` if `text` is missing, the body isn't JSON, or `conversationId` has other characters than the ones above.
+**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.
 
 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.
 
@@ -97,6 +98,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 /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

@@ -36,6 +36,8 @@ export type HttpProviderDeps = {
     linking?: ChannelLinking;
     /** 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;
 };
 export declare function createHttpProvider(deps: HttpProviderDeps): Provider & {
     stop(): Promise<void>;

package/dist/http-server.d.ts

@@ -60,6 +60,11 @@ export declare function openApiResponse(corsOrigin?: string): Response;
  * one-on-one (`multiUser: false`). No `conversationId` means a fresh ephemeral
  * session. Never throws: a refused caller is a 401, a bad body a 400, a
  * mid-turn failure an `error` event on the stream.
+ *
+ * `{ opening: true, conversationId }`, with no `text`, asks the assistant to
+ * speak first in that conversation (right after someone signs in): the core
+ * decides whether it has anything to say, and a `final` with an empty text
+ * means it hasn't.
  */
 export declare function handleTurnRequest(req: Request, deps: TurnRequestDeps): Promise<Response>;
 export type ConfirmRequestDeps = {
@@ -102,10 +107,12 @@ export type CompleteLoginFn = (state: string, code: string) => Promise<LoginOutc
  * in, with `code` and `state` (or `error`, when they refused). Public: the
  * person's browser carries no token here, and the single-use `state` the core
  * issued for them is what ties the request to their login. Answers with a
- * plain page telling them how it went.
+ * plain page telling them how it went, naming the assistant as the app does
+ * (`Mercury` from an older core that doesn't say).
  */
 export declare function handleLoginCallback(req: Request, deps: {
     complete: CompleteLoginFn;
+    assistantName?: string;
 }): Promise<Response>;
 /** A single read route: its `GET` handler plus the shared `OPTIONS` preflight. */
 type ReadRoute = {
@@ -133,6 +140,8 @@ export type HttpServerDeps = TurnRequestDeps & {
     completeLogin?: CompleteLoginFn;
     /** Linking another account to the caller; `/link` is mounted only with it. */
     linking?: ChannelLinking;
+    /** What the pages people read call the assistant. */
+    assistantName?: string;
 };
 /** Starts the HTTP surface: `POST /turn` (4a) plus the read-only routes (4b)
  * when `reads` is supplied. */

package/http-provider.ts

@@ -33,6 +33,8 @@ export type HttpProviderDeps = {
   linking?: ChannelLinking;
   /** 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;
 };
 
 export function createHttpProvider(deps: HttpProviderDeps): Provider & { stop(): Promise<void> } {
@@ -51,6 +53,7 @@ export function createHttpProvider(deps: HttpProviderDeps): Provider & { stop():
         completeLogin: deps.logins?.complete,
         ...(deps.linking === undefined ? {} : { linking: deps.linking }),
         ...(deps.resumeMaxChars === undefined ? {} : { resumeMaxChars: deps.resumeMaxChars }),
+        ...(deps.assistantName === undefined ? {} : { assistantName: deps.assistantName }),
       });
       deps.logins?.accept(deps.logins.callbackUrl);
     },

package/http-server.ts

@@ -147,24 +147,33 @@ export function openApiResponse(corsOrigin = "*"): Response {
  * one-on-one (`multiUser: false`). No `conversationId` means a fresh ephemeral
  * session. Never throws: a refused caller is a 401, a bad body a 400, a
  * mid-turn failure an `error` event on the stream.
+ *
+ * `{ opening: true, conversationId }`, with no `text`, asks the assistant to
+ * speak first in that conversation (right after someone signs in): the core
+ * decides whether it has anything to say, and a `final` with an empty text
+ * means it hasn't.
  */
 export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Promise<Response> {
   const origin = deps.corsOrigin ?? "*";
   const cors = corsHeaders(origin);
   const principal = await caller(req, deps, origin);
   if (principal instanceof Response) return principal;
-  let body: { text?: unknown; conversationId?: unknown };
+  let body: { text?: unknown; conversationId?: unknown; opening?: unknown };
   try {
     body = (await req.json()) as typeof body;
   } catch {
     return Response.json({ ok: false, error: "body must be JSON" }, { status: 400, headers: cors });
   }
-  if (typeof body.text !== "string" || body.text.trim().length === 0) {
-    return Response.json({ ok: false, error: "missing text" }, { status: 400, headers: cors });
-  }
-  const text = body.text;
+  const opening = body.opening === true;
   // A conversation the client names is one it reopens; an ephemeral one never comes back.
   const named = typeof body.conversationId === "string" && body.conversationId.trim().length > 0;
+  if (opening && !named) {
+    return Response.json({ ok: false, error: "an opening needs a conversationId" }, { status: 400, headers: cors });
+  }
+  if (!opening && (typeof body.text !== "string" || body.text.trim().length === 0)) {
+    return Response.json({ ok: false, error: "missing text" }, { status: 400, headers: cors });
+  }
+  const text = opening ? "" : (body.text as string);
   const conversationId = named ? (body.conversationId as string).trim() : (deps.newSessionKey ?? (() => crypto.randomUUID()))();
   if (!CONVERSATION_ID.test(conversationId)) {
     return Response.json({ ok: false, error: "invalid conversationId" }, { status: 400, headers: cors });
@@ -198,7 +207,7 @@ 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 = await deps.confirm(text, sessionKey, principal);
+      const confirmReply = opening ? null : await deps.confirm(text, sessionKey, principal);
       if (confirmReply !== null) {
         send("final", { text: confirmReply });
         close();
@@ -236,6 +245,7 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
             logPrefix: `[http:${forLog(sessionKey)}] `,
             abortSignal: abort.signal,
             ...(named ? { resume: deps.resumeMaxChars === undefined ? {} : { maxChars: deps.resumeMaxChars } } : {}),
+            ...(opening ? { opening: true as const } : {}),
           },
           sink,
         );
@@ -352,18 +362,23 @@ function loginPage(text: string, status: number): Response {
  * in, with `code` and `state` (or `error`, when they refused). Public: the
  * person's browser carries no token here, and the single-use `state` the core
  * issued for them is what ties the request to their login. Answers with a
- * plain page telling them how it went.
+ * plain page telling them how it went, naming the assistant as the app does
+ * (`Mercury` from an older core that doesn't say).
  */
-export async function handleLoginCallback(req: Request, deps: { complete: CompleteLoginFn }): Promise<Response> {
+export async function handleLoginCallback(
+  req: Request,
+  deps: { complete: CompleteLoginFn; assistantName?: string },
+): Promise<Response> {
+  const assistant = deps.assistantName ?? "Mercury";
   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 Mercury again for a new link.`, 400);
+    return loginPage(`The login didn't happen (${reason}). Ask ${assistant} again for a new link.`, 400);
   }
   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 Mercury again for a new link.", 400);
+  if (!code || !state) return loginPage(`The login link came back without a code or a state. Ask ${assistant} again for a new link.`, 400);
   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)
@@ -371,8 +386,15 @@ export async function handleLoginCallback(req: Request, deps: { complete: Comple
 }
 
 /** The login callback route, mounted when the server can complete logins. */
-function loginRoutes(complete: CompleteLoginFn): Record<string, { GET: (req: Request) => Promise<Response> }> {
-  return { "/login/callback": { GET: (req) => handleLoginCallback(req, { complete }) } };
+function loginRoutes(
+  complete: CompleteLoginFn,
+  assistantName: string | undefined,
+): Record<string, { GET: (req: Request) => Promise<Response> }> {
+  return {
+    "/login/callback": {
+      GET: (req) => handleLoginCallback(req, { complete, ...(assistantName === undefined ? {} : { assistantName }) }),
+    },
+  };
 }
 
 /** A single read route: its `GET` handler plus the shared `OPTIONS` preflight. */
@@ -437,6 +459,16 @@ export function readRoutes(
       });
     }),
     "/tool-log": route(async (_req, principal) => json({ ok: true, entries: await reads.toolLog(principal) })),
+    // Who the caller is to the core, on a core that can say.
+    ...(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 });
+          }),
+        }),
     "/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) })),
     "/wiki/read": route(async (req, principal) => {
@@ -471,6 +503,8 @@ export type HttpServerDeps = TurnRequestDeps & {
   completeLogin?: CompleteLoginFn;
   /** Linking another account to the caller; `/link` is mounted only with it. */
   linking?: ChannelLinking;
+  /** What the pages people read call the assistant. */
+  assistantName?: string;
 };
 
 /** Starts the HTTP surface: `POST /turn` (4a) plus the read-only routes (4b)
@@ -502,7 +536,7 @@ export function startHttpServer(deps: HttpServerDeps): ReturnType<typeof Bun.ser
       },
       "/openapi.yaml": { GET: () => openApiResponse(origin), OPTIONS: () => preflight(origin) },
       ...(deps.reads ? readRoutes(deps.reads, deps.authenticate, origin, deps.admit) : {}),
-      ...(deps.completeLogin ? loginRoutes(deps.completeLogin) : {}),
+      ...(deps.completeLogin ? loginRoutes(deps.completeLogin, deps.assistantName) : {}),
       ...(deps.linking ? linkRoutes({ ...deps, start: deps.linking.start, corsOrigin: origin }) : {}),
     },
     error: (err) =>

package/index.ts

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

package/openapi.yaml

@@ -85,7 +85,11 @@ paths:
         Runs one model turn and streams the result as `text/event-stream`. If
         `text` is a pending confirmation token it is resolved deterministically
         without ever consulting the model. Close the connection to cancel an
-        in-flight turn.
+        in-flight turn. With `opening: true` and no `text`, the assistant
+        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.
       requestBody:
         required: true
         content:
@@ -113,7 +117,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/TurnEvent"
         "400":
-          description: Missing/invalid body, or a conversationId with characters outside the allowed ones.
+          description: Missing/invalid body, an opening without a conversationId, or a conversationId with characters outside the allowed ones.
           content:
             application/json:
               schema:
@@ -305,6 +309,32 @@ paths:
             application/json:
               schema:
                 type: object
+  /me:
+    get:
+      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.
+      responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
+        "200":
+          description: The caller's name, or null.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [ok, name]
+                properties:
+                  ok:
+                    type: boolean
+                  name:
+                    type: [string, "null"]
   /tool-log:
     get:
       summary: The tool calls made in the caller's recent turns
@@ -519,11 +549,14 @@ components:
   schemas:
     TurnRequest:
       type: object
-      required: [text]
       properties:
         text:
           type: string
-          description: The user's message, or a bare confirmation token.
+          description: The user's message, or a bare confirmation token. Required, unless `opening` is true.
+        opening:
+          type: boolean
+          enum: [true]
+          description: The assistant speaks first in `conversationId`, which is then required; `text` is ignored.
         conversationId:
           type: string
           pattern: "^[A-Za-z0-9_-]{1,128}$"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/channel-http",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -18,11 +18,11 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@mercury-fw/channel-types": ">=0.45.0 <1.0.0"
+    "@mercury-fw/channel-types": ">=0.49.0 <1.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-types": "0.47.0",
-    "@mercury-fw/plugin-types": "0.47.0",
+    "@mercury-fw/channel-types": "0.49.0",
+    "@mercury-fw/plugin-types": "0.49.0",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"