@mercury-fw/channel-http 0.15.1 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @mercury-fw/channel-http
 
+## 0.16.0
+
+### Minor Changes
+
+- 07d1ef6: - conversations get a title, generated from the first question and its answer after the first turn the person wrote
+  - channel contract: optional `ctx.conversations` with `rename`, the title the person chose, never replaced by a generated one
+  - `GET /conversations` and `GET /conversation` carry `title` once a conversation has one
+  - `PATCH /conversation?id=<conversationId>` with `{ title }` renames one of the caller's conversations
+
 ## 0.15.1
 
 ### Patch Changes

package/README.md

@@ -97,6 +97,10 @@ A code for linking another of the caller's accounts to them, for the UI to show:
 
 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.
 
+## `PATCH /conversation`
+
+Renames one of the caller's conversations: `?id=<conversationId>`, body `{ title }`; returns `{ ok: true, title }` with the title as saved (trimmed). A title has at most 100 characters, on one line: an empty one, a longer one or one with a line break is `400` with the reason, as are a missing or malformed `id` and a body without `title`. `404` when no conversation of the caller's has that id: only a conversation with at least one turn in the archive can be renamed. Mercury never replaces a title the person chose. Not there on a core that can't rename conversations.
+
 ## `POST /confirm`
 
 Explicit alternative to re-sending a token as `/turn` `text`. Body `{ token, conversationId }`; returns `{ ok: true, resolved: true, text }` when the token was a pending confirmation (`text`: the core's reply in the caller's language, "Confirmed and done." or the failure, never the action's raw result), `{ ok: true, resolved: false }` otherwise. When the confirmed action hands its result back to the model, it returns `{ ok: true, resolved: true, resume: true }` instead: open `POST /turn { resume: true, conversationId }` to hear the model's answer. `400` if `token` or `conversationId` is missing, or the id has other characters than `/turn` accepts. Never invokes the model.
@@ -107,8 +111,8 @@ All `GET`, all JSON, all reporting state already held in-process. They need an a
 
 | endpoint | `data` on success |
 |---|---|
-| `GET /conversation?id=<conversationId>&limit=<n>&offset=<cursor>` | `{ messages: [{ role, content, interrupted?, trace?, pendingNote?, confirmation?, timestamp }], nextOffset }` — one of your conversations, its durable transcript in order, each answer as you saw it with the lists it showed (empty for an id that isn't yours). An answer whose turn was cancelled has `interrupted: true` and an empty `content`: the question before it was left unanswered. An answer's `trace` is what its turn showed besides the text, in order, as the events above showed it: each reasoning block in full, each status line with its tool and outcome, each confirmation staged (its command and its choices' labels, named by an `id`, never a token), each login asked for (its service, never the link); up to the stop for a cancelled turn. `pendingNote` is the turn's `final` one. A message with `confirmation: { id, status, choice? }` says how the staged action with that `id` (its trace entry) was resolved (`ok`, `failed`, or `resume`, whose answer is the next message): its `content` is the reply you got, empty for `resume`. Answers archived before these fields have none of them. `400` if `id` is missing or has other characters than `/turn` accepts |
-| `GET /conversations?limit=<n>` | `{ conversations: [{ conversationId, lastTimestamp, preview }] }` — your conversations, most-recently-active first; the preview is the newest message that shows something, so the question when the last answer was interrupted |
+| `GET /conversation?id=<conversationId>&limit=<n>&offset=<cursor>` | `{ messages: [{ role, content, interrupted?, trace?, pendingNote?, confirmation?, timestamp }], nextOffset, title? }` — one of your conversations, its durable transcript in order, each answer as you saw it with the lists it showed (empty for an id that isn't yours). An answer whose turn was cancelled has `interrupted: true` and an empty `content`: the question before it was left unanswered. An answer's `trace` is what its turn showed besides the text, in order, as the events above showed it: each reasoning block in full, each status line with its tool and outcome, each confirmation staged (its command and its choices' labels, named by an `id`, never a token), each login asked for (its service, never the link); up to the stop for a cancelled turn. `pendingNote` is the turn's `final` one. A message with `confirmation: { id, status, choice? }` says how the staged action with that `id` (its trace entry) was resolved (`ok`, `failed`, or `resume`, whose answer is the next message): its `content` is the reply you got, empty for `resume`. Answers archived before these fields have none of them. `400` if `id` is missing or has other characters than `/turn` accepts |
+| `GET /conversations?limit=<n>` | `{ conversations: [{ conversationId, lastTimestamp, preview, title? }] }` — your conversations, most-recently-active first; the preview is the newest message that shows something, so the question when the last answer was interrupted |
 | `GET /manifest` | `{ manifest: { coreApiVersion, plugins: [{ name, apiVersion, active, skills, hasBuild, customStatus }], activeClis, skills } }` |
 | `GET /confirmations` | `{ pending: [{ sessionKey, summary, expiresAt }] }` — your pending confirmations; tokens are deliberately never included |
 | `GET /me` | `{ name, language, 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 |
@@ -122,6 +126,8 @@ All `GET`, all JSON, all reporting state already held in-process. They need an a
 
 Conversation history and the conversation list are backed by the durable verbatim archive; they degrade to empty when the vector store is unreachable.
 
+**Titles.** A few seconds after the first turn the person wrote in a conversation, Mercury names it from that first question and its answer (after the next turn if it couldn't, for instance with the model unreachable: until then the conversation has no title), and the title stays the same from then on; the person can rename it (`PATCH /conversation`), and Mercury never replaces a title they chose. `title` is there on both `GET /conversation` and `GET /conversations` once the conversation has one; until then, `preview` is what there is to show. A UI that wants the title of a new conversation reads the list again shortly after the turn's stream closes.
+
 ## `GET /version`
 
 Which Mercury this is, for a UI to show: `{ ok: true, version }`, the framework's version as `major.minor.patch` (`"0.59.0"`), the one of `@mercury-fw/core`, not this channel's own. When the app's config declares its own version (`version` in `mercury.config.ts`, its `package.json`'s, as a scaffolded app does), it comes too, as it is: `{ ok: true, version: "0.65.0", app: { version: "1.2.0" } }`. A new one shows once the app is rebuilt. It needs no token, so anyone who reaches the port sees both.

package/dist/http-provider.d.ts

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

package/dist/http-server.d.ts

@@ -22,7 +22,7 @@
  * Confirm resolution is injected too (`confirm`/`resolveConfirmation`), so this
  * package never imports the app.
  */
-import { type HandleTurn, type Authenticate, type ChannelHostReads, type ChannelI18n, type ChannelRuntimeContext, type LoginOutcome, type Principal, type Admission, type ChannelLinking, type ChannelSettings } from "@mercury-fw/channel-types";
+import { type HandleTurn, type Authenticate, type ChannelHostReads, type ChannelI18n, type ChannelRuntimeContext, type LoginOutcome, type Principal, type Admission, type ChannelLinking, type ChannelSettings, type ChannelConversations } from "@mercury-fw/channel-types";
 /** Resolves a bare confirmation token to what to tell the person, or `null` if the input isn't a token. Injected by the core (`ctx.confirm`). */
 export type ConfirmFn = ChannelRuntimeContext["confirm"];
 /** The structured sibling of {@link ConfirmFn}, for the `/confirm` `resolved` flag. Injected by the core (`ctx.resolveConfirmation`). */
@@ -124,10 +124,10 @@ export declare function handleLoginCallback(req: Request, deps: {
     assistantName?: string;
     i18n?: ChannelI18n;
 }): Promise<Response>;
-/** A single read route: its `GET` handler plus the shared `OPTIONS` preflight, and on `/me` the `PATCH` saving a setting. */
+/** A single read route: its `GET` handler plus the shared `OPTIONS` preflight, and on `/me` and `/conversation` the `PATCH` changing what it reads. */
 type ReadRoute = {
     GET: (req: Request) => Response | Promise<Response>;
-    /** Only on `/me`, when the core offers the person's settings (`PATCH /me`). */
+    /** On `/me` when the core offers the person's settings (`PATCH /me`), on `/conversation` when it renames conversations (`PATCH /conversation`). */
     PATCH?: (req: Request) => Promise<Response>;
     OPTIONS: () => Response;
 };
@@ -141,9 +141,11 @@ type ReadRoute = {
  * `/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. With `settings`, `/me` also takes a `PATCH` saving the
- * caller's time zone (a UI's settings area), asking `authenticate` first too.
+ * caller's time zone (a UI's settings area), asking `authenticate` first too;
+ * with `conversations`, `/conversation` takes a `PATCH` renaming one of the
+ * caller's conversations, the same way.
  */
-export declare function readRoutes(reads: ChannelHostReads, authenticate: Authenticate, corsOrigin?: string, admit?: AdmitFn, settings?: ChannelSettings): Record<string, ReadRoute>;
+export declare function readRoutes(reads: ChannelHostReads, authenticate: Authenticate, corsOrigin?: string, admit?: AdmitFn, settings?: ChannelSettings, conversations?: ChannelConversations): Record<string, ReadRoute>;
 export type HttpServerDeps = TurnRequestDeps & {
     port: number;
     reads?: ChannelHostReads;
@@ -155,6 +157,8 @@ export type HttpServerDeps = TurnRequestDeps & {
     linking?: ChannelLinking;
     /** The person's own settings; `PATCH /me` is mounted only with it. */
     settings?: ChannelSettings;
+    /** Renaming the person's conversations; `PATCH /conversation` is mounted only with it. */
+    conversations?: ChannelConversations;
     /** What the pages people read call the assistant. */
     assistantName?: string;
     /** The framework's version; `/version` is mounted only with it. */

package/http-provider.ts

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

package/http-server.ts

@@ -36,6 +36,7 @@ import {
   type Admission,
   type ChannelLinking,
   type ChannelSettings,
+  type ChannelConversations,
 } from "@mercury-fw/channel-types";
 import { englishHttp } from "./messages.ts";
 
@@ -457,10 +458,10 @@ function loginRoutes(
   };
 }
 
-/** A single read route: its `GET` handler plus the shared `OPTIONS` preflight, and on `/me` the `PATCH` saving a setting. */
+/** A single read route: its `GET` handler plus the shared `OPTIONS` preflight, and on `/me` and `/conversation` the `PATCH` changing what it reads. */
 type ReadRoute = {
   GET: (req: Request) => Response | Promise<Response>;
-  /** Only on `/me`, when the core offers the person's settings (`PATCH /me`). */
+  /** On `/me` when the core offers the person's settings (`PATCH /me`), on `/conversation` when it renames conversations (`PATCH /conversation`). */
   PATCH?: (req: Request) => Promise<Response>;
   OPTIONS: () => Response;
 };
@@ -475,7 +476,9 @@ type ReadRoute = {
  * `/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. With `settings`, `/me` also takes a `PATCH` saving the
- * caller's time zone (a UI's settings area), asking `authenticate` first too.
+ * caller's time zone (a UI's settings area), asking `authenticate` first too;
+ * with `conversations`, `/conversation` takes a `PATCH` renaming one of the
+ * caller's conversations, the same way.
  */
 export function readRoutes(
   reads: ChannelHostReads,
@@ -483,6 +486,7 @@ export function readRoutes(
   corsOrigin = "*",
   admit?: AdmitFn,
   settings?: ChannelSettings,
+  conversations?: ChannelConversations,
 ): Record<string, ReadRoute> {
   const cors = corsHeaders(corsOrigin);
   const json = (payload: object, status = 200): Response =>
@@ -500,26 +504,49 @@ export function readRoutes(
   return {
     "/manifest": route(async (_req, principal) => json({ ok: true, manifest: await reads.manifest(principal) })),
     "/confirmations": route(async (_req, principal) => json({ ok: true, pending: await reads.pendingConfirmations(principal) })),
-    "/conversation": route(async (req, principal) => {
-      const url = new URL(req.url);
-      const id = url.searchParams.get("id");
-      if (!id) return badRequest("missing ?id");
-      if (!CONVERSATION_ID.test(id)) return badRequest("invalid conversationId");
-      const limit = Number(url.searchParams.get("limit") ?? "200");
-      const offset = url.searchParams.get("offset") ?? undefined;
-      return json({ ok: true, ...(await reads.conversation(principal, `${principal.id}:${id}`, limit, offset) as object) });
-    }),
+    "/conversation": {
+      ...route(async (req, principal) => {
+        const url = new URL(req.url);
+        const id = url.searchParams.get("id");
+        if (!id) return badRequest("missing ?id");
+        if (!CONVERSATION_ID.test(id)) return badRequest("invalid conversationId");
+        const limit = Number(url.searchParams.get("limit") ?? "200");
+        const offset = url.searchParams.get("offset") ?? undefined;
+        return json({ ok: true, ...(await reads.conversation(principal, `${principal.id}:${id}`, limit, offset) as object) });
+      }),
+      ...(conversations === undefined
+        ? {}
+        : {
+            PATCH: async (req: Request) => {
+              const principal = await caller(req, { authenticate, ...(admit === undefined ? {} : { admit }) }, corsOrigin);
+              if (principal instanceof Response) return principal;
+              const id = new URL(req.url).searchParams.get("id");
+              if (!id) return badRequest("missing ?id");
+              if (!CONVERSATION_ID.test(id)) return badRequest("invalid conversationId");
+              const body = (await req.json().catch(() => null)) as { title?: unknown } | null;
+              if (typeof body?.title !== "string") return badRequest('the body must be {"title": "<text>"}');
+              const renamed = await conversations.rename(principal, `${principal.id}:${id}`, body.title);
+              if (renamed.ok) return json({ ok: true, title: renamed.title });
+              return renamed.notFound ? json({ ok: false, error: renamed.error }, 404) : badRequest(renamed.error);
+            },
+          }),
+    },
     "/conversations": route(async (req, principal) => {
       const limit = Number(new URL(req.url).searchParams.get("limit") ?? "50");
       const { conversations } = (await reads.conversations(principal, limit)) as {
-        conversations: Array<{ sessionKey: string; lastTimestamp: string; preview: string }>;
+        conversations: Array<{ sessionKey: string; lastTimestamp: string; preview: string; title?: string }>;
       };
       const prefix = `${principal.id}:`;
       return json({
         ok: true,
         conversations: conversations
           .filter((c) => c.sessionKey.startsWith(prefix))
-          .map((c) => ({ conversationId: c.sessionKey.slice(prefix.length), lastTimestamp: c.lastTimestamp, preview: c.preview })),
+          .map((c) => ({
+            conversationId: c.sessionKey.slice(prefix.length),
+            lastTimestamp: c.lastTimestamp,
+            preview: c.preview,
+            ...(c.title === undefined ? {} : { title: c.title }),
+          })),
       });
     }),
     "/tool-log": route(async (_req, principal) => json({ ok: true, entries: await reads.toolLog(principal) })),
@@ -604,6 +631,8 @@ export type HttpServerDeps = TurnRequestDeps & {
   linking?: ChannelLinking;
   /** The person's own settings; `PATCH /me` is mounted only with it. */
   settings?: ChannelSettings;
+  /** Renaming the person's conversations; `PATCH /conversation` is mounted only with it. */
+  conversations?: ChannelConversations;
   /** What the pages people read call the assistant. */
   assistantName?: string;
   /** The framework's version; `/version` is mounted only with it. */
@@ -642,7 +671,7 @@ export function startHttpServer(deps: HttpServerDeps): ReturnType<typeof Bun.ser
       },
       "/openapi.yaml": { GET: () => openApiResponse(origin), OPTIONS: () => preflight(origin) },
       ...(deps.version === undefined ? {} : versionRoutes(deps.version, deps.appVersion, origin)),
-      ...(deps.reads ? readRoutes(deps.reads, deps.authenticate, origin, deps.admit, deps.settings) : {}),
+      ...(deps.reads ? readRoutes(deps.reads, deps.authenticate, origin, deps.admit, deps.settings, deps.conversations) : {}),
       ...(deps.completeLogin ? loginRoutes(deps.completeLogin, deps.assistantName, deps.i18n) : {}),
       ...(deps.linking ? linkRoutes({ ...deps, start: deps.linking.start, corsOrigin: origin }) : {}),
     },

package/index.ts

@@ -49,6 +49,7 @@ export const httpChannel: ChannelPlugin = {
       i18n: ctx.i18n,
       ...(ctx.linking === undefined ? {} : { linking: ctx.linking }),
       ...(ctx.settings === undefined ? {} : { settings: ctx.settings }),
+      ...(ctx.conversations === undefined ? {} : { conversations: ctx.conversations }),
       ...(resumeMaxChars === undefined ? {} : { resumeMaxChars }),
       ...(ctx.assistantName === undefined ? {} : { assistantName: ctx.assistantName }),
       ...(ctx.frameworkVersion === undefined ? {} : { version: ctx.frameworkVersion }),

package/openapi.yaml

@@ -49,6 +49,14 @@ info:
     by the verbatim archive; they degrade to empty when the vector store is
     unreachable).
 
+    A conversation has a title once Mercury has named it, a few seconds after
+    the first turn the person wrote in it, from that first question and its
+    answer (after the next turn if it couldn't, for instance with the model
+    unreachable); it then stays the same. The caller renames one of their
+    conversations with `PATCH /conversation`, and Mercury never replaces a
+    title the person chose. Until there is a title, `title` is absent from
+    both reads and `preview` is what there is to show.
+
     A conversation never ends: sent again with the same `conversationId`, a
     turn continues it however long after. Mercury frees a conversation's
     in-memory history once it has been idle a while; the next turn rebuilds
@@ -273,6 +281,64 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
+    patch:
+      summary: Renames one of the caller's conversations
+      description: >
+        Gives the conversation the title the caller chose, trimmed, in place of
+        the one it had; Mercury never replaces it with one it generates. Only a
+        conversation already in the archive (one with a turn) can be renamed.
+        Not there on a core that can't rename conversations.
+      parameters:
+        - name: id
+          in: query
+          required: true
+          description: The caller's `conversationId`, as `/conversations` lists it.
+          schema:
+            type: string
+            pattern: "^[A-Za-z0-9_-]{1,128}$"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [title]
+              properties:
+                title:
+                  type: string
+                  description: At most 100 characters once trimmed, on one line.
+      responses:
+        "400":
+          description: Missing or malformed `?id`, a body with no `title`, or a title that is empty, longer than 100 characters or holds a line break.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "404":
+          description: No conversation of the caller's has this id.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
+        "200":
+          description: The title as saved.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [ok, title]
+                properties:
+                  ok:
+                    type: boolean
+                    enum: [true]
+                  title:
+                    type: string
   /conversations:
     get:
       summary: List the caller's conversations (most-recently-active first)
@@ -932,6 +998,9 @@ components:
           oneOf:
             - type: string
             - type: "null"
+        title:
+          type: string
+          description: The conversation's title, Mercury's or the caller's; absent until it has one.
     ConversationSummary:
       type: object
       required: [conversationId, lastTimestamp, preview]
@@ -943,6 +1012,9 @@ components:
         preview:
           type: string
           description: The newest message that shows something, as the person saw it, so the question when the last answer was interrupted.
+        title:
+          type: string
+          description: The conversation's title, Mercury's or the caller's; absent until it has one, when `preview` is what there is to show.
     ConversationList:
       type: object
       required: [ok, conversations]

package/package.json

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