@mercury-fw/channel-http 0.16.0 → 0.17.0

package/CHANGELOG.md

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

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
@@ -99,7 +99,7 @@ Saves the caller's time zone, for a UI's settings: body `{ timeZone }`, an IANA
 
 ## `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.
+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`
 
@@ -107,7 +107,7 @@ Explicit alternative to re-sending a token as `/turn` `text`. Body `{ token, con
 
 ## 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 |
 |---|---|
@@ -117,11 +117,11 @@ All `GET`, all JSON, all reporting state already held in-process. They need an a
 | `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.

package/http-server.ts

@@ -494,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);
@@ -504,51 +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 === 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");
+    // 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 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);
-            },
+              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 }),
+                })),
+            });
           }),
-    },
-    "/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; 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
@@ -593,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) });
+          }),
+        }),
   };
 }
 

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

package/openapi.yaml

@@ -242,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
@@ -342,6 +343,7 @@ paths:
   /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
@@ -378,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
@@ -586,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/channel-http",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -18,11 +18,11 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@mercury-fw/channel-types": ">=0.70.0 <1.0.0"
+    "@mercury-fw/channel-types": ">=0.73.0 <1.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-types": "0.70.0",
-    "@mercury-fw/plugin-types": "0.70.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"