@mercury-fw/channel-http 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @mercury-fw/channel-http
 
+## 0.8.0
+
+### Minor Changes
+
+- 812c9c5: - A conversation reopened on the HTTP surface after Mercury freed its history comes back to the model: the summaries of its older part plus its newest messages from the archive, within a budget.
+  - What a resumed conversation brings back isn't captured to long-term memory again, only the new messages are.
+  - `SESSION_RESUME_MAX_CHARS` sets how much comes back (default 30000, `0` turns it off); `HTTP_SURFACE_RESUME_MAX_CHARS` sets it for the HTTP surface only.
+  - `InboundTurn.resume` lets a channel mark a conversation its client reopens.
+  - The episodic collection gets a `sessionKey` index.
+  - `mfw create` lists `HTTP_SURFACE_RESUME_MAX_CHARS` for the HTTP channel.
+  - Core's README explains how Mercury remembers a conversation.
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -21,6 +21,7 @@ It needs an auth provider next to it: [`@mercury-fw/auth-oidc`](../../auth/auth-
 | `HTTP_SURFACE_PORT` | The port (default `4100`). |
 | `HTTP_SURFACE_CORS_ORIGIN` | The origin a browser UI calls from (default `*`). |
 | `HTTP_SURFACE_PUBLIC_URL` | The address people's browsers reach the surface at (e.g. `https://mercury.example.com`). With it, people log in here to the services plugins act on as them (see [`GET /login/callback`](#get-logincallback)); without it, nobody can. |
+| `HTTP_SURFACE_RESUME_MAX_CHARS` | How many characters of a reopened conversation come back to the model once Mercury has freed its history (default: the core's `SESSION_RESUME_MAX_CHARS`; `0` turns resuming off on this surface). See [how Mercury remembers a conversation](../../libs/core/README.md#how-mercury-remembers-a-conversation). |
 
 ## API
 
@@ -45,7 +46,7 @@ Runs one conversational turn; the reply streams back as Server-Sent Events.
 | field | type | required | description |
 |---|---|---|---|
 | `text` | string | yes | The user message. A bare confirmation token here confirms a staged action (see the `pending` event) without invoking the model. |
-| `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. Omitted ⇒ a fresh one-off session. |
+| `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, the body isn't JSON, or `conversationId` has other characters than the ones above.
 

package/dist/http-provider.d.ts

@@ -34,6 +34,8 @@ export type HttpProviderDeps = {
     };
     /** Linking another account to the caller (`POST /link`). */
     linking?: ChannelLinking;
+    /** The surface's budget for a reopened conversation (`HTTP_SURFACE_RESUME_MAX_CHARS`). */
+    resumeMaxChars?: number;
 };
 export declare function createHttpProvider(deps: HttpProviderDeps): Provider & {
     stop(): Promise<void>;

package/dist/http-server.d.ts

@@ -40,6 +40,8 @@ export type TurnRequestDeps = {
     corsOrigin?: string;
     /** Test seam for the ephemeral session key when the client sends no conversationId. */
     newSessionKey?: () => string;
+    /** How much of a reopened conversation comes back once the core let its history go (`HTTP_SURFACE_RESUME_MAX_CHARS`); absent, the core's own. */
+    resumeMaxChars?: number;
 };
 /**
  * Serves the OpenAPI document that describes this surface — the single source

package/http-provider.ts

@@ -31,6 +31,8 @@ export type HttpProviderDeps = {
   logins?: { callbackUrl: string; accept: (callbackUrl: string) => void; complete: CompleteLoginFn };
   /** Linking another account to the caller (`POST /link`). */
   linking?: ChannelLinking;
+  /** The surface's budget for a reopened conversation (`HTTP_SURFACE_RESUME_MAX_CHARS`). */
+  resumeMaxChars?: number;
 };
 
 export function createHttpProvider(deps: HttpProviderDeps): Provider & { stop(): Promise<void> } {
@@ -48,6 +50,7 @@ export function createHttpProvider(deps: HttpProviderDeps): Provider & { stop():
         corsOrigin: deps.corsOrigin,
         completeLogin: deps.logins?.complete,
         ...(deps.linking === undefined ? {} : { linking: deps.linking }),
+        ...(deps.resumeMaxChars === undefined ? {} : { resumeMaxChars: deps.resumeMaxChars }),
       });
       deps.logins?.accept(deps.logins.callbackUrl);
     },

package/http-server.ts

@@ -69,6 +69,8 @@ export type TurnRequestDeps = {
   corsOrigin?: string;
   /** Test seam for the ephemeral session key when the client sends no conversationId. */
   newSessionKey?: () => string;
+  /** How much of a reopened conversation comes back once the core let its history go (`HTTP_SURFACE_RESUME_MAX_CHARS`); absent, the core's own. */
+  resumeMaxChars?: number;
 };
 
 const SSE_HEADERS = {
@@ -161,10 +163,9 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
     return Response.json({ ok: false, error: "missing text" }, { status: 400, headers: cors });
   }
   const text = body.text;
-  const conversationId =
-    typeof body.conversationId === "string" && body.conversationId.trim().length > 0
-      ? body.conversationId.trim()
-      : (deps.newSessionKey ?? (() => crypto.randomUUID()))();
+  // A conversation the client names is one it reopens; an ephemeral one never comes back.
+  const named = typeof body.conversationId === "string" && body.conversationId.trim().length > 0;
+  const conversationId = named ? (body.conversationId as string).trim() : (deps.newSessionKey ?? (() => crypto.randomUUID()))();
   if (!CONVERSATION_ID.test(conversationId)) {
     return Response.json({ ok: false, error: "invalid conversationId" }, { status: 400, headers: cors });
   }
@@ -234,6 +235,7 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
             // The caller's id comes from the auth provider, unchecked here.
             logPrefix: `[http:${forLog(sessionKey)}] `,
             abortSignal: abort.signal,
+            ...(named ? { resume: deps.resumeMaxChars === undefined ? {} : { maxChars: deps.resumeMaxChars } } : {}),
           },
           sink,
         );

package/index.ts

@@ -35,6 +35,7 @@ export const httpChannel: ChannelPlugin = {
     // the address their browser reaches the surface at.
     const publicUrl = ctx.env.HTTP_SURFACE_PUBLIC_URL?.trim().replace(/\/+$/, "");
     const logins = publicUrl ? ctx.logins : undefined;
+    const resumeMaxChars = parseResumeMaxChars(ctx.env.HTTP_SURFACE_RESUME_MAX_CHARS);
     return createHttpProvider({
       port: Number(ctx.env.HTTP_SURFACE_PORT ?? "4100"),
       corsOrigin: ctx.env.HTTP_SURFACE_CORS_ORIGIN ?? "*",
@@ -44,7 +45,16 @@ export const httpChannel: ChannelPlugin = {
       authenticate: ctx.authenticate,
       admit: ctx.admit,
       ...(ctx.linking === undefined ? {} : { linking: ctx.linking }),
+      ...(resumeMaxChars === undefined ? {} : { resumeMaxChars }),
       ...(logins ? { logins: { callbackUrl: `${publicUrl}/login/callback`, accept: logins.accept, complete: logins.complete } } : {}),
     });
   },
 };
+
+/** `HTTP_SURFACE_RESUME_MAX_CHARS`: unset or empty leaves the core's budget, otherwise a whole number from 0 up (0 turns resuming off on this surface); throws on anything else. */
+function parseResumeMaxChars(text: string | undefined): number | undefined {
+  const trimmed = text?.trim() ?? "";
+  if (trimmed === "") return undefined;
+  if (!/^\d+$/.test(trimmed)) throw new Error(`HTTP_SURFACE_RESUME_MAX_CHARS must be a whole number from 0 up, got "${trimmed}"`);
+  return Number(trimmed);
+}

package/openapi.yaml

@@ -49,6 +49,13 @@ info:
     by the verbatim archive; they degrade to empty when the vector store is
     unreachable).
 
+    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
+    it from the archive (a summary of its older part and its newest messages,
+    within `HTTP_SURFACE_RESUME_MAX_CHARS`), so the model still knows what the
+    person sees on screen.
+
 
     ## Streaming and cancellation
 
@@ -520,7 +527,7 @@ components:
         conversationId:
           type: string
           pattern: "^[A-Za-z0-9_-]{1,128}$"
-          description: Opaque, client-owned; letters, digits, `-` and `_` (a UUID fits). Omit to start a fresh ephemeral conversation.
+          description: Opaque, client-owned; letters, digits, `-` and `_` (a UUID fits). Omit to start a fresh ephemeral conversation, which can't be continued.
     TurnEvent:
       type: object
       description: The shape carried by each SSE `data:` line, per event type.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/channel-http",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -21,8 +21,8 @@
     "@mercury-fw/channel-types": ">=0.36.0 <1.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-types": "0.44.0",
-    "@mercury-fw/plugin-types": "0.44.0",
+    "@mercury-fw/channel-types": "0.45.0",
+    "@mercury-fw/plugin-types": "0.45.0",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"