@mercury-fw/channel-http 0.13.0 → 0.13.2

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @mercury-fw/channel-http
 
+## 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
+
+- f631dd5: README: a link to the package's page on Mercury's documentation site (https://lucabro81.github.io/mercury-fw/), published from this release on. The HTTP channel's README points to the HTTP API reference there, and the core's memory section to the page that explains it.
+
 ## 0.13.0
 
 ### Minor Changes

package/README.md

@@ -2,7 +2,9 @@
 
 Gives a [Mercury](https://github.com/lucabro81/mercury-fw) agent an HTTP surface to build a custom UI on: one conversational turn per request, streamed back as Server-Sent Events, plus confirmation and read-only routes over what the agent holds (conversations, the wiki, memory, its plugins).
 
-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.
+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.61 or later, the first whose core says when a resumed turn's answer is no longer available (`resume` below); since 0.59 the core gives channels its version (`GET /version`). A core with an older contract skips it, and the log says why.
 
 ```bash
 bun add @mercury-fw/channel-http
@@ -35,7 +37,7 @@ It's active whenever it's declared in `mercury.config.ts`'s `channels` with an a
 
 **CORS** is enabled on every response and every route answers an `OPTIONS` preflight, so a browser UI on another origin can call it. The allowed origin is `HTTP_SURFACE_CORS_ORIGIN` (default `*`: the token travels in a header, never in a cookie the browser would send on its own).
 
-The full contract is described by an **OpenAPI document**, served raw at `GET /openapi.yaml` and published as a rendered docs page on GitHub Pages (see `packages/channels/channel-http/openapi.yaml`, the single source of truth).
+The full contract is described by an **OpenAPI document**, served raw at `GET /openapi.yaml` and published as [the HTTP API reference](https://lucabro81.github.io/mercury-fw/reference/http-api/) on the documentation site (see `packages/channels/channel-http/openapi.yaml`, the single source of truth).
 
 All responses are JSON except `POST /turn`, which streams `text/event-stream`. Every JSON response is either `{ "ok": true, ... }` or, on error, `{ "ok": false, "error": "<message>" }` with HTTP `400`/`401`/`500`.
 
@@ -49,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.

package/dist/http-server.d.ts

@@ -47,9 +47,9 @@ export type TurnRequestDeps = {
 };
 /**
  * Serves the OpenAPI document that describes this surface — the single source
- * of truth in this package's `openapi.yaml`, also rendered as the GitHub Pages
- * API docs. Served raw as `text/yaml` (no YAML parser needed at runtime); most
- * tooling (Redoc, Swagger UI, Postman) reads YAML directly.
+ * of truth in this package's `openapi.yaml`, also rendered as the docs site's
+ * HTTP API reference. Served raw as `text/yaml` (no YAML parser needed at
+ * runtime); most tooling (Redoc, Swagger UI, Postman) reads YAML directly.
  */
 export declare function openApiResponse(corsOrigin?: string): Response;
 /**

package/http-server.ts

@@ -153,9 +153,9 @@ function preflight(origin: string): Response {
 
 /**
  * Serves the OpenAPI document that describes this surface — the single source
- * of truth in this package's `openapi.yaml`, also rendered as the GitHub Pages
- * API docs. Served raw as `text/yaml` (no YAML parser needed at runtime); most
- * tooling (Redoc, Swagger UI, Postman) reads YAML directly.
+ * of truth in this package's `openapi.yaml`, also rendered as the docs site's
+ * HTTP API reference. Served raw as `text/yaml` (no YAML parser needed at
+ * runtime); most tooling (Redoc, Swagger UI, Postman) reads YAML directly.
  */
 export function openApiResponse(corsOrigin = "*"): Response {
   const file = Bun.file(new URL("./openapi.yaml", import.meta.url));

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:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/channel-http",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "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.61.0 <1.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-types": "0.59.0",
-    "@mercury-fw/plugin-types": "0.59.0",
+    "@mercury-fw/channel-types": "0.61.0",
+    "@mercury-fw/plugin-types": "0.61.0",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"