@mercury-fw/channel-http 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @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
+
+- 2c63bbf: One person across accounts: linking them by a code.
+
+  - `POST /link` on the HTTP surface hands the caller a one-time code (`xxxx-xxxx-xxxx`, ten minutes, single use). They send it from the other account, on any channel, twice. The first time Mercury says whom the account would be linked to, the second time it links it.
+  - From then on the account is the person it's linked to: one private area, one memory, the same roles. Its earlier area stays where it was, and undoing the link gives it back.
+  - A link never touches the terminal, never chains, and is refused for an account the directory already knows as someone else.
+  - The links live on the vault's volume, out of the vault's git and out of reach of the model and the HTTP reads.
+  - `mfw identity links | link | unlink` lets the operator manage them, for instances where nobody can be shown a code.
+  - Channels get the code through the confirmation hook they already call (`ctx.confirm`), and the HTTP surface gets `ctx.linking`.
+  - Fixed: `ctx.confirm` refused someone the core doesn't admit before checking that their text was a token at all. On Google Chat, every message from an unknown sender came back as the refusal.
+
 ## 0.6.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.
 
@@ -78,6 +79,10 @@ Where a person comes back after logging in to a service a plugin acts on as them
 
 Whoever opens the link and accepts decides which account gets linked: a link belongs to the person it was shown to, and someone else accepting it would link their own account to that person's Mercury identity. A UI should say so next to the link. Checking the linked account against the person is [#179](https://github.com/lucabro81/mercury-fw/issues/179).
 
+## `POST /link`
+
+A code for linking another of the caller's accounts to them, for the UI to show: `{ ok: true, code, expiresAt }`, or `400` with the reason when there's none. The person sends the code from the other account, on any channel, twice: the first time Mercury says whom the account would be linked to, the second time it links it, and from then on both accounts are one person (one private area, the same roles). The code lasts ten minutes, works once, and only the caller sees it; the model never does. It belongs to the first account that sends it, so it should be sent in a one-to-one conversation, never in a shared space where someone else could send it first. Over HTTP only an account the instance already admits can send it (anyone else is refused before the turn), so an account a closed instance doesn't know links from a chat.
+
 ## `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, `{ ok: true, resolved: false }` otherwise. `400` if `token` or `conversationId` is missing, or the id has other characters than `/turn` accepts. Never invokes the model.

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 } from "@mercury-fw/channel-types";
+import type { Authenticate, Provider, ChannelHostReads, ChannelLinking } from "@mercury-fw/channel-types";
 export type HttpProviderDeps = {
     port: number;
     /** Bare-token interception before the model. */
@@ -32,6 +32,10 @@ export type HttpProviderDeps = {
         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 declare function createHttpProvider(deps: HttpProviderDeps): Provider & {
     stop(): Promise<void>;

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 ConfirmOutcome, type LoginOutcome, type Principal, type Admission } from "@mercury-fw/channel-types";
+import { type HandleTurn, type Authenticate, type ChannelHostReads, type ConfirmOutcome, type LoginOutcome, type Principal, type Admission, type ChannelLinking } from "@mercury-fw/channel-types";
 /** Resolves a bare confirmation token to a reply string, or `null` if the input isn't a token. Injected by the core (`ctx.confirm`). */
 export type ConfirmFn = (token: string, sessionKey: string, principal: Principal) => Promise<string | null>;
 /** The structured sibling of {@link ConfirmFn}, for the `/confirm` `resolved` flag. Injected by the core (`ctx.resolveConfirmation`). */
@@ -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
@@ -79,6 +81,20 @@ export type ConfirmRequestDeps = {
  * even token-shaped). Never touches the model.
  */
 export declare function handleConfirmRequest(req: Request, deps: ConfirmRequestDeps): Promise<Response>;
+export type LinkRequestDeps = {
+    authenticate: Authenticate;
+    admit?: AdmitFn;
+    /** Hands the caller a link code, injected by the core (`ctx.linking.start`). */
+    start: ChannelLinking["start"];
+    corsOrigin?: string;
+};
+/**
+ * `POST /link` — a one-time code for linking another account to the caller
+ * (the custom UI shows it). The person then sends it from the other account,
+ * on any channel. Nobody but the caller ever sees it, the model included, and
+ * it isn't cached. `400` with the core's reason when there's no code for them.
+ */
+export declare function handleLinkRequest(req: Request, deps: LinkRequestDeps): Promise<Response>;
 /** Finishes a person's login, injected by the core (`ChannelLogins.complete`). */
 export type CompleteLoginFn = (state: string, code: string) => Promise<LoginOutcome>;
 /**
@@ -115,6 +131,8 @@ export type HttpServerDeps = TurnRequestDeps & {
     resolveConfirmation: ResolveConfirmationFn;
     /** Finishes people's logins; `/login/callback` is mounted only with it. */
     completeLogin?: CompleteLoginFn;
+    /** Linking another account to the caller; `/link` is mounted only with it. */
+    linking?: ChannelLinking;
 };
 /** Starts the HTTP surface: `POST /turn` (4a) plus the read-only routes (4b)
  * when `reads` is supplied. */

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 } from "@mercury-fw/channel-types";
+import type { Authenticate, Provider, HandleTurn, ChannelHostReads, ChannelLinking } from "@mercury-fw/channel-types";
 
 export type HttpProviderDeps = {
   port: number;
@@ -29,6 +29,10 @@ export type HttpProviderDeps = {
   /** People's logins, when the surface has a public URL to be sent back to:
    * the callback is offered (`accept`) once the server listens. */
   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> } {
@@ -45,6 +49,8 @@ export function createHttpProvider(deps: HttpProviderDeps): Provider & { stop():
         ...(deps.admit === undefined ? {} : { admit: deps.admit }),
         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

@@ -34,6 +34,7 @@ import {
   type LoginOutcome,
   type Principal,
   type Admission,
+  type ChannelLinking,
 } from "@mercury-fw/channel-types";
 
 /**
@@ -68,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 = {
@@ -160,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 });
   }
@@ -233,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,
         );
@@ -305,6 +308,33 @@ export async function handleConfirmRequest(req: Request, deps: ConfirmRequestDep
   }
 }
 
+export type LinkRequestDeps = {
+  authenticate: Authenticate;
+  admit?: AdmitFn;
+  /** Hands the caller a link code, injected by the core (`ctx.linking.start`). */
+  start: ChannelLinking["start"];
+  corsOrigin?: string;
+};
+
+/**
+ * `POST /link` — a one-time code for linking another account to the caller
+ * (the custom UI shows it). The person then sends it from the other account,
+ * on any channel. Nobody but the caller ever sees it, the model included, and
+ * it isn't cached. `400` with the core's reason when there's no code for them.
+ */
+export async function handleLinkRequest(req: Request, deps: LinkRequestDeps): Promise<Response> {
+  const origin = deps.corsOrigin ?? "*";
+  const principal = await caller(req, deps, origin);
+  if (principal instanceof Response) return principal;
+  const started = await deps.start(principal);
+  return Response.json(started, { status: started.ok ? 200 : 400, headers: { ...corsHeaders(origin), "cache-control": "no-store" } });
+}
+
+/** `POST /link` and its preflight, mounted when the core offers linking. */
+function linkRoutes(deps: LinkRequestDeps): Record<string, { POST: (req: Request) => Promise<Response>; OPTIONS: () => Response }> {
+  return { "/link": { POST: (req) => handleLinkRequest(req, deps), OPTIONS: () => preflight(deps.corsOrigin ?? "*") } };
+}
+
 /** Finishes a person's login, injected by the core (`ChannelLogins.complete`). */
 export type CompleteLoginFn = (state: string, code: string) => Promise<LoginOutcome>;
 
@@ -439,6 +469,8 @@ export type HttpServerDeps = TurnRequestDeps & {
   resolveConfirmation: ResolveConfirmationFn;
   /** Finishes people's logins; `/login/callback` is mounted only with it. */
   completeLogin?: CompleteLoginFn;
+  /** Linking another account to the caller; `/link` is mounted only with it. */
+  linking?: ChannelLinking;
 };
 
 /** Starts the HTTP surface: `POST /turn` (4a) plus the read-only routes (4b)
@@ -471,6 +503,7 @@ export function startHttpServer(deps: HttpServerDeps): ReturnType<typeof Bun.ser
       "/openapi.yaml": { GET: () => openApiResponse(origin), OPTIONS: () => preflight(origin) },
       ...(deps.reads ? readRoutes(deps.reads, deps.authenticate, origin, deps.admit) : {}),
       ...(deps.completeLogin ? loginRoutes(deps.completeLogin) : {}),
+      ...(deps.linking ? linkRoutes({ ...deps, start: deps.linking.start, corsOrigin: origin }) : {}),
     },
     error: (err) =>
       Response.json(

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 ?? "*",
@@ -43,7 +44,17 @@ export const httpChannel: ChannelPlugin = {
       reads: ctx.reads,
       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
 
@@ -146,6 +153,45 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
+  /link:
+    post:
+      summary: A code for linking another account to the caller
+      description: >
+        A one-time code (`xxxx-xxxx-xxxx`, valid for ten minutes) the person
+        sends from another account, on any channel, twice: the first time
+        Mercury says whom the account would be linked to, the second time it
+        links it. From then on both accounts are one person. Only the caller
+        sees the code; the model never does.
+      responses:
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/NotAdmitted"
+        "503":
+          $ref: "#/components/responses/NotAdmitted"
+        "400":
+          description: No code for this caller, with the reason.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "200":
+          description: The code and when it expires.
+          content:
+            application/json:
+              schema:
+                type: object
+                required: [ok, code, expiresAt]
+                properties:
+                  ok:
+                    type: boolean
+                    enum: [true]
+                  code:
+                    type: string
+                    pattern: "^[A-Za-z0-9]{4}-[A-Za-z0-9]{4}-[A-Za-z0-9]{4}$"
+                  expiresAt:
+                    type: string
+                    format: date-time
   /conversation:
     get:
       summary: A conversation's durable transcript
@@ -481,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.6.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.42.0",
-    "@mercury-fw/plugin-types": "0.42.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"