@mercury-fw/channel-http 0.13.1 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mercury-fw/channel-http
 
+## 0.14.0
+
+### Minor Changes
+
+- 7a76257: - `GET /version` also answers the app's own version when its config declares one: `{ ok: true, version, app: { version } }`. Still no token; without one the body is the same as before.
+  - Needs the framework at 0.65 or later (peer range raised).
+
+## 0.13.2
+
+### Patch Changes
+
+- 1e7fdeb: - `POST /turn { resume: true }` with nothing left to resume streams a single `final` whose text says the answer is no longer available, instead of an empty one, which a UI shows like any answer; an empty `final` now always means the model had nothing to add.
+  - Needs the framework at 0.61 or later (peer range raised).
+
 ## 0.13.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.59 or later, the first whose core gives channels its version (`GET /version`). A core with an older contract skips it, and the log says why.
+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.
 
 ```bash
 bun add @mercury-fw/channel-http
@@ -51,7 +51,7 @@ Runs one conversational turn; the reply streams back as Server-Sent Events.
 |---|---|---|---|
 | `text` | string | yes, unless `opening` or `resume` | The user message. A bare confirmation token here confirms a staged action (see the `pending` event) without invoking the model; when the action hands its result back to the model, the model's answer streams on this same request. |
 | `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. |
-| `resume` | `true` | no | The turn a `POST /confirm` answered `resume: true` for: the model answers on what the confirmed action handed back. Needs `conversationId`; `text` is ignored. With nothing to resume, the stream is a single `final` with an empty text. |
+| `resume` | `true` | no | The turn a `POST /confirm` answered `resume: true` for: the model answers on what the confirmed action handed back. Needs `conversationId`; `text` is ignored. With nothing left to resume (more than five minutes after the confirmation, a restart in between, or a turn already resumed), the stream is a single `final` whose text says the answer is no longer available, in the person's language. |
 | `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, an opening has no `conversationId`, the body isn't JSON, or `conversationId` has other characters than the ones above.
@@ -117,11 +117,11 @@ All `GET`, all JSON, all reporting state already held in-process. They need an a
 | `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); `400` for any other collection |
+| `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); `400` for any other collection |
 | `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.
 
 ## `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. It needs no token.
+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" } }`. The app moves that number itself, and 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

@@ -44,6 +44,8 @@ export type HttpProviderDeps = {
     i18n?: ChannelI18n;
     /** The framework's version, served on `/version` (`ctx.frameworkVersion`). */
     version?: string;
+    /** The app's own version, served on `/version` next to it (`ctx.appVersion`). */
+    appVersion?: string;
 };
 export declare function createHttpProvider(deps: HttpProviderDeps): Provider & {
     stop(): Promise<void>;

package/dist/http-server.d.ts

@@ -159,6 +159,8 @@ export type HttpServerDeps = TurnRequestDeps & {
     assistantName?: string;
     /** The framework's version; `/version` is mounted only with it. */
     version?: string;
+    /** The app's own version, served on `/version` next to the framework's. */
+    appVersion?: string;
 };
 /** Starts the HTTP surface: `POST /turn` (4a) plus the read-only routes (4b)
  * when `reads` is supplied. */

package/http-provider.ts

@@ -41,6 +41,8 @@ export type HttpProviderDeps = {
   i18n?: ChannelI18n;
   /** The framework's version, served on `/version` (`ctx.frameworkVersion`). */
   version?: string;
+  /** The app's own version, served on `/version` next to it (`ctx.appVersion`). */
+  appVersion?: string;
 };
 
 export function createHttpProvider(deps: HttpProviderDeps): Provider & { stop(): Promise<void> } {
@@ -63,6 +65,7 @@ export function createHttpProvider(deps: HttpProviderDeps): Provider & { stop():
         ...(deps.assistantName === undefined ? {} : { assistantName: deps.assistantName }),
         ...(deps.i18n === undefined ? {} : { i18n: deps.i18n }),
         ...(deps.version === undefined ? {} : { version: deps.version }),
+        ...(deps.appVersion === undefined ? {} : { appVersion: deps.appVersion }),
       });
       deps.logins?.accept(deps.logins.callbackUrl);
     },

package/http-server.ts

@@ -580,13 +580,15 @@ export function readRoutes(
 }
 
 /**
- * `GET /version`: which Mercury this is (the framework's version), for any
- * front end to show. Nobody is asked who they are, like `/openapi.yaml`.
+ * `GET /version`: which Mercury this is (the framework's version, and the
+ * app's own when it declares one), for any front end to show. Nobody is asked
+ * who they are, like `/openapi.yaml`.
  */
-function versionRoutes(version: string, corsOrigin = "*"): Record<string, ReadRoute> {
+function versionRoutes(version: string, appVersion: string | undefined, corsOrigin = "*"): Record<string, ReadRoute> {
+  const body = appVersion === undefined ? { ok: true, version } : { ok: true, version, app: { version: appVersion } };
   return {
     "/version": {
-      GET: () => Response.json({ ok: true, version }, { headers: corsHeaders(corsOrigin) }),
+      GET: () => Response.json(body, { headers: corsHeaders(corsOrigin) }),
       OPTIONS: () => preflight(corsOrigin),
     },
   };
@@ -607,6 +609,8 @@ export type HttpServerDeps = TurnRequestDeps & {
   assistantName?: string;
   /** The framework's version; `/version` is mounted only with it. */
   version?: string;
+  /** The app's own version, served on `/version` next to the framework's. */
+  appVersion?: string;
 };
 
 /** Starts the HTTP surface: `POST /turn` (4a) plus the read-only routes (4b)
@@ -638,7 +642,7 @@ export function startHttpServer(deps: HttpServerDeps): ReturnType<typeof Bun.ser
         OPTIONS: () => preflight(origin),
       },
       "/openapi.yaml": { GET: () => openApiResponse(origin), OPTIONS: () => preflight(origin) },
-      ...(deps.version === undefined ? {} : versionRoutes(deps.version, origin)),
+      ...(deps.version === undefined ? {} : versionRoutes(deps.version, deps.appVersion, origin)),
       ...(deps.reads ? readRoutes(deps.reads, deps.authenticate, origin, deps.admit, deps.settings) : {}),
       ...(deps.completeLogin ? loginRoutes(deps.completeLogin, deps.assistantName, deps.i18n) : {}),
       ...(deps.linking ? linkRoutes({ ...deps, start: deps.linking.start, corsOrigin: origin }) : {}),

package/index.ts

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

package/openapi.yaml

@@ -80,7 +80,9 @@ info:
     (a page read after the caller allowed it, for example). Confirming one by
     `POST /turn` streams the model's answer on that same stream; `POST /confirm`
     answers `resume: true`, and the client then opens
-    `POST /turn { resume: true, conversationId }` to hear it.
+    `POST /turn { resume: true, conversationId }` to hear it. The answer waits
+    five minutes and is heard once: later, after a restart, or a second time,
+    that `final`'s text says it's no longer available.
 security:
   - bearerAuth: []
 servers:
@@ -593,12 +595,13 @@ paths:
     get:
       summary: Which Mercury this is
       description: >
-        The framework's version, `major.minor.patch`, for a UI to show. Needs
-        no bearer token.
+        The framework's version, `major.minor.patch`, for a UI to show, and
+        the app's own when its config declares one (`app.version`, its
+        `package.json`'s, shown as the app has it). Needs no bearer token.
       security: []
       responses:
         "200":
-          description: The framework's version.
+          description: The framework's version, and the app's when it declares one.
           content:
             application/json:
               schema:
@@ -610,6 +613,15 @@ paths:
                     type: string
                     pattern: '^\d+\.\d+\.\d+$'
                     examples: ["0.59.0"]
+                  app:
+                    type: object
+                    description: The app's own version; absent when the app declares none.
+                    required: [version]
+                    properties:
+                      version:
+                        type: string
+                        description: As the app's `package.json` has it, not checked.
+                        examples: ["1.2.0"]
   /openapi.yaml:
     get:
       summary: This OpenAPI document

package/package.json

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