@mercury-fw/channel-http 0.8.4 → 0.9.0

package/CHANGELOG.md

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

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-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 = {

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,
         );
@@ -449,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) => {

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.4",
+  "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.48.0",
-    "@mercury-fw/plugin-types": "0.48.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"