@mercury-fw/channel-http 0.15.1 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @mercury-fw/channel-http
 
+## 0.17.0
+
+### Minor Changes
+
+- fb1f30a: - conversation-store contract: `ConversationStorePlugin`, `ConversationStore`, `StoredMessage`, `StoredTitle`, `CONVERSATION_STORE_API_VERSION`
+  - `conversationStore` in `mercury.config.ts`: where every conversation's messages and title are kept
+  - **Breaking:** without `conversationStore` nothing is archived: no reopened or listed conversations, no titles, no `recall_verbatim`
+  - `qdrantConversations()` in `@mercury-fw/store-qdrant`: messages in `conversation_messages` (`QDRANT_MESSAGES_COLLECTION`), titles in `conversation_titles` (`QDRANT_TITLES_COLLECTION`); on start, copies the messages of `verbatim_archive` into `conversation_messages` once, marking the copy done only when all are in
+  - `@mercury-fw/core` no longer depends on `@qdrant/js-client-rest` and no longer reads `QDRANT_URL`
+  - **Breaking:** `GET /health` (HTTP): `conversationStoreReachable` and `vectorIndexReachable` (`null` when not declared) instead of `qdrantReachable`
+  - **Breaking:** channel contract 7: `ChannelHostReads.conversation`, `conversations` and `memoryScroll` optional, given only with a conversation store / a vector index; channels written for contract 6 are refused
+  - `channel-http`, `channel-google-chat`: channel contract 7, framework 0.73 or later
+  - `channel-http`: `/conversation`, `/conversations` (`GET`, `PATCH`) only with a conversation store, `/memory/scroll` only with a vector index; `404` otherwise
+  - `system.start` trace event: `conversationStore` (`declared`, `active`)
+  - `mfw create`: new apps declare `conversationStore: qdrantConversations()`
+  - **Migration:** in `mercury.config.ts`, import `qdrantConversations` from `@mercury-fw/store-qdrant` and add `conversationStore: qdrantConversations(),`; upgrade `@mercury-fw/channel-http` and `@mercury-fw/channel-google-chat` with the framework; a UI reading `qdrantReachable` from `/health` reads the two new fields
+
+### Patch Changes
+
+- b634bd1: - vector-index contract: `VectorIndexPlugin`, `VectorIndex`, `VectorPoint`, `VectorSpaceSpec`, `VectorWhere`, `VECTOR_INDEX_API_VERSION`
+  - `vectorIndex` in `mercury.config.ts`: where episodes, semantic facts, procedural corrections and `recall_verbatim`'s search are kept
+  - **Breaking:** without `vectorIndex` there is no long-term memory: no conversation summaries, no corrections, no `recall_verbatim` (tool and prompt), idle conversations closed without a summary
+  - new package `@mercury-fw/store-qdrant`: `qdrantIndex()`, Qdrant at `QDRANT_URL`, each space the collection of the same name or the one its `QDRANT_*_COLLECTION` names
+  - the memory's vector length comes from the embedding model at startup; `QDRANT_*_VECTOR_SIZE` no longer read
+  - `GET /memory/scroll` (HTTP) takes the index's space name (`episodic_memory`, `semantic_facts`, `verbatim_archive`), not the `QDRANT_*_COLLECTION` name
+  - `system.start` trace event: `vectorIndex` (`declared`, `active`)
+  - `mfw memory` runs the memory CLI of `@mercury-fw/store-qdrant`
+  - `mfw create`: new apps declare `vectorIndex: qdrantIndex()` and depend on `@mercury-fw/store-qdrant`
+  - **Migration:** add `@mercury-fw/store-qdrant` to the app's dependencies, at the framework's version; in `mercury.config.ts`, `import { qdrantIndex } from "@mercury-fw/store-qdrant";` and `vectorIndex: qdrantIndex(),`; `QDRANT_*_VECTOR_SIZE` can go from `.env`
+
+## 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

@@ -4,7 +4,7 @@ Gives a [Mercury](https://github.com/lucabro81/mercury-fw) agent an HTTP surface
 
 On Mercury's documentation site: [its page](https://lucabro81.github.io/mercury-fw/plugins/channel-http/).
 
-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.65 or later, the first whose core gives channels the app's version (`GET /version`); since 0.61 the core says when a resumed turn's answer is no longer available (`resume` below). A core with an older contract skips it, and the log says why.
+This version is written for version 7 of the channel contract, the one whose conversation and memory reads are there only when the agent keeps them, and needs the framework at 0.73 or later; since 0.61 the core says when a resumed turn's answer is no longer available (`resume` below). A core with an older contract skips it, and the log says why.
 
 ```bash
 bun add @mercury-fw/channel-http
@@ -97,31 +97,37 @@ 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 an agent with no conversation store (`404`).
+
 ## `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.
 
 ## Read-only introspection
 
-All `GET`, all JSON, all reporting state already held in-process. They need an authenticated caller and show only what belongs to them: their conversations, confirmations, tool calls and memory, and the wiki as they see it (the team's `curated/` plus their own notes as `personal/`). Someone else's data doesn't exist as far as a caller can tell. `/manifest` lists what the caller is offered (a plugin acting as Mercury only for someone allowed to use it), and only `/health` is the same for everyone.
+All `GET`, all JSON, all reporting state already held in-process. `/conversation` and `/conversations` exist only on an agent with a conversation store, `/memory/scroll` only on one with a vector index: on any other they answer `404`, as an unknown route does. They need an authenticated caller and show only what belongs to them: their conversations, confirmations, tool calls and memory, and the wiki as they see it (the team's `curated/` plus their own notes as `personal/`). Someone else's data doesn't exist as far as a caller can tell. `/manifest` lists what the caller is offered (a plugin acting as Mercury only for someone allowed to use it), and only `/health` is the same for everyone.
 
 | 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 |
 | `GET /tool-log` | `{ entries: [...] }` — the tool calls of your recent turns |
-| `GET /health` | `{ uptimeSeconds, memory, qdrantReachable, ollamaReachable }` |
+| `GET /health` | `{ uptimeSeconds, memory, conversationStoreReachable, vectorIndexReachable, ollamaReachable }` — whether each answers, `null` for one the agent doesn't declare |
 | `GET /wiki/list` | `{ files: [...] }` — `curated/...` and `personal/...` paths |
 | `GET /wiki/read?path=<path>` | `{ content }` — a path as `/wiki/list` gives it; `400` if `path` is missing, `404` if it isn't among yours |
 | `GET /wiki/grep?pattern=<regex>` | `{ matches: [...] }` — `400` if `pattern` is missing |
-| `GET /memory/scroll?collection=<name>&limit=<n>&offset=<cursor>` | one page of your points in a collection kept per person (verbatim archive, episodic memory, semantic facts), each with its whole payload (a verbatim answer's `displays` and `calls` included, and an interrupted answer's `interrupted: true` with the note the model gets in its `content`); `400` for any other collection |
+| `GET /memory/scroll?collection=<name>&limit=<n>&offset=<cursor>` | one page of your points in a space of the vector index kept per person (`verbatim_archive`, `episodic_memory`, `semantic_facts`), each with its whole payload (a verbatim answer's `displays` and `calls` included, and an interrupted answer's `interrupted: true` with the note the model gets in its `content`); `400` for any other |
 | `GET /openapi.yaml` | the OpenAPI document for this surface (`text/yaml`) |
 
 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 =>
@@ -490,6 +494,8 @@ export function readRoutes(
   const badRequest = (message: string): Response => json({ ok: false, error: message }, 400);
   const requireParam = (req: Request, name: string): string | null => new URL(req.url).searchParams.get(name);
   const options = () => preflight(corsOrigin);
+  // Read once, so each stays narrowed inside its routes.
+  const { conversation, conversations: listConversations, memoryScroll } = reads;
   const route = (GET: (req: Request, principal: Principal) => Response | Promise<Response>): ReadRoute => ({
     GET: async (req) => {
       const principal = await caller(req, { authenticate, ...(admit === undefined ? {} : { admit }) }, corsOrigin);
@@ -500,28 +506,56 @@ 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) });
-    }),
-    "/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 }>;
-      };
-      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 })),
-      });
-    }),
+    // The conversations, on an instance that keeps them.
+    ...(conversation === undefined || listConversations === undefined
+      ? {}
+      : {
+          "/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 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 listConversations(principal, limit)) as {
+              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,
+                  ...(c.title === undefined ? {} : { title: c.title }),
+                })),
+            });
+          }),
+        }),
     "/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
@@ -566,15 +600,20 @@ export function readRoutes(
       if (!pattern) return badRequest("missing ?pattern");
       return json({ ok: true, matches: await reads.wikiGrep(principal, pattern) });
     }),
-    "/memory/scroll": route(async (req, principal) => {
-      const url = new URL(req.url);
-      const collection = url.searchParams.get("collection");
-      if (!collection) return badRequest("missing ?collection");
-      const limit = Number(url.searchParams.get("limit") ?? "50");
-      const offset = url.searchParams.get("offset") ?? undefined;
-      const page = await reads.memoryScroll(principal, collection, limit, offset);
-      return page === null ? badRequest(`unknown collection: ${collection}`) : json({ ok: true, ...(page as object) });
-    }),
+    // The memory, on an instance with a vector index.
+    ...(memoryScroll === undefined
+      ? {}
+      : {
+          "/memory/scroll": route(async (req, principal) => {
+            const url = new URL(req.url);
+            const collection = url.searchParams.get("collection");
+            if (!collection) return badRequest("missing ?collection");
+            const limit = Number(url.searchParams.get("limit") ?? "50");
+            const offset = url.searchParams.get("offset") ?? undefined;
+            const page = await memoryScroll(principal, collection, limit, offset);
+            return page === null ? badRequest(`unknown collection: ${collection}`) : json({ ok: true, ...(page as object) });
+          }),
+        }),
   };
 }
 
@@ -604,6 +643,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 +683,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

@@ -23,7 +23,7 @@ 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: 6,
+  apiVersion: 7,
   name: "http",
   messages: HTTP_MESSAGES,
   build: (ctx) => {
@@ -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
@@ -234,6 +242,7 @@ paths:
   /conversation:
     get:
       summary: A conversation's durable transcript
+      description: Only on an agent with a conversation store; `404` on any other.
       parameters:
         - name: id
           in: query
@@ -273,9 +282,68 @@ 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)
+      description: Only on an agent with a conversation store; `404` on any other.
       parameters:
         - name: limit
           in: query
@@ -312,6 +380,21 @@ paths:
             application/json:
               schema:
                 type: object
+                properties:
+                  ok:
+                    type: boolean
+                  uptimeSeconds:
+                    type: number
+                  memory:
+                    type: object
+                  conversationStoreReachable:
+                    type: [boolean, "null"]
+                    description: Whether the declared conversation store answers; `null` when the agent declares none.
+                  vectorIndexReachable:
+                    type: [boolean, "null"]
+                    description: Whether the declared vector index answers; `null` when the agent declares none.
+                  ollamaReachable:
+                    type: boolean
   /manifest:
     get:
       summary: The plugins, tools and skills the caller is offered
@@ -520,11 +603,12 @@ paths:
   /memory/scroll:
     get:
       summary: Scroll the caller's points in a memory collection
+      description: Only on an agent with a vector index; `404` on any other.
       parameters:
         - name: collection
           in: query
           required: true
-          description: One of the collections kept per person (the verbatim archive, episodic memory, semantic facts), by its configured name.
+          description: One of the vector index's spaces kept per person, by name (`verbatim_archive`, `episodic_memory`, `semantic_facts`).
           schema:
             type: string
         - name: limit
@@ -932,6 +1016,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 +1030,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.17.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.73.0 <1.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-types": "0.69.0",
-    "@mercury-fw/plugin-types": "0.69.0",
+    "@mercury-fw/channel-types": "0.73.0",
+    "@mercury-fw/plugin-types": "0.73.0",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"