@mercury-fw/channel-http 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mercury-fw/channel-http
 
+## 0.10.0
+
+### Minor Changes
+
+- b2f8cfb: - A confirmation can offer several choices (for example "only this time" / "always for this host"): a plugin tool stages them with the new `stageChoices` of `SessionToolContext`, and gets one token per choice. The person takes one; the others die with it, and they all expire together.
+  - The paper-trail note of a group of choices is one, under its first token, and says which choice was taken.
+  - `detectPendingConfirmation` returns the `choices` a staging offers; a plain staging is one choice labelled `Conferma`.
+  - A confirmed action can hand its result back to the model (`resume` on a choice): instead of showing the person the raw result, the channel resumes the turn and the model answers on it, the result reaching it as the tool result of the call that staged it, never stored in the history.
+  - A resumed turn answers the person who confirmed even in a shared space, and the line standing for the confirmation isn't archived as something they said. A result nobody resumes within five minutes (the life of a confirmation token) is forgotten, and a restart loses it.
+  - `InboundTurn.resumeAfterConfirm` and `RESUME_AFTER_CONFIRM` (channel contract) carry the resumed turn; `ConfirmOutcome` has a `resume` status.
+  - Terminal: every choice is printed on its own line with its token; a confirmation that resumes runs the turn again.
+  - Google Chat: the confirmation card has one button per choice; a typed token or a clicked choice that resumes runs the turn again, in the session's queue. The channel now needs channel-types 0.51.0 or later.
+  - HTTP: the `pending` event carries `choices`; a token sent to `POST /turn` that resumes streams the model's answer on the same request; `POST /confirm` answers `resume: true`, and `POST /turn { resume: true, conversationId }` runs that turn. The channel now needs channel-types 0.51.0 or later.
+
 ## 0.9.0
 
 ### Minor Changes

package/README.md

@@ -45,8 +45,9 @@ Runs one conversational turn; the reply streams back as Server-Sent Events.
 
 | field | type | required | description |
 |---|---|---|---|
-| `text` | string | yes, unless `opening` | The user message. A bare confirmation token here confirms a staged action (see the `pending` event) without invoking the model. |
+| `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. |
 | `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.
@@ -62,7 +63,7 @@ Reasoning and answer text arrive as **incremental deltas** — never one finishe
 | `tool` | `{ label, detail, toolCallId, name }` | a tool call starts; `name` is the tool the model called, absent when Mercury is saving something to memory |
 | `tool_finish` | `{ toolCallId, outcome }` | a tool call settles (`outcome`: `success` \| `failed` \| `pending`) |
 | `text` | `{ chunk }` | an answer-text delta |
-| `pending` | `{ command, token }` | a confirm-required action was staged; send `token` back to confirm it — as a later `/turn` `text`, or via `POST /confirm` |
+| `pending` | `{ command, token, choices }` | a confirm-required action was staged; send a token back to confirm it — as a later `/turn` `text`, or via `POST /confirm`. `choices` is every way to answer (`{ token, label }`, in order; one, labelled `Conferma`, for a plain staging): the others die with the one sent |
 | `login` | `{ service, url }` | the caller isn't logged in to `service` yet, which a plugin acts on as them: show them `url` to open (the model never gets it) |
 | `final` | `{ text }` | the complete answer (also emitted for a token confirmation, with no model turn) |
 | `error` | `{ message }` | the turn failed mid-stream |
@@ -86,7 +87,7 @@ A code for linking another of the caller's accounts to them, for the UI to show:
 
 ## `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.
+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. When the confirmed action hands its result back to the model, it returns `{ ok: true, resolved: true, resume: true }` instead: open `POST /turn { resume: true, conversationId }` to hear the model's answer. `400` if `token` or `conversationId` is missing, or the id has other characters than `/turn` accepts. Never invokes the model.
 
 ## Read-only introspection
 

package/dist/http-server.d.ts

@@ -64,7 +64,9 @@ export declare function openApiResponse(corsOrigin?: string): Response;
  * `{ opening: true, conversationId }`, with no `text`, asks the assistant to
  * speak first in that conversation (right after someone signs in): the core
  * decides whether it has anything to say, and a `final` with an empty text
- * means it hasn't.
+ * means it hasn't. `{ resume: true, conversationId }` runs the turn a
+ * `/confirm` answered `resume: true` for; a bare token whose confirmation
+ * resumes runs that turn on the same stream.
  */
 export declare function handleTurnRequest(req: Request, deps: TurnRequestDeps): Promise<Response>;
 export type ConfirmRequestDeps = {
@@ -83,7 +85,9 @@ export type ConfirmRequestDeps = {
  * pending confirmation and its staged action was consumed and run; the `text`
  * then reports whether that execution succeeded. `resolved: false` means the
  * token was not a pending confirmation (unknown, expired, already used, or not
- * even token-shaped). Never touches the model.
+ * even token-shaped). `resume: true` (with no `text`) means the action handed
+ * its result back to the model: the client hears its answer by opening
+ * `/turn { resume: true, conversationId }`. Never touches the model.
  */
 export declare function handleConfirmRequest(req: Request, deps: ConfirmRequestDeps): Promise<Response>;
 export type LinkRequestDeps = {

package/http-server.ts

@@ -26,6 +26,7 @@ import {
   detectLoginRequired,
   detectPendingConfirmation,
   PENDING_CONFIRMATION_NOTE,
+  RESUME_AFTER_CONFIRM,
   type HandleTurn,
   type TurnSink,
   type Authenticate,
@@ -151,14 +152,16 @@ export function openApiResponse(corsOrigin = "*"): Response {
  * `{ opening: true, conversationId }`, with no `text`, asks the assistant to
  * speak first in that conversation (right after someone signs in): the core
  * decides whether it has anything to say, and a `final` with an empty text
- * means it hasn't.
+ * means it hasn't. `{ resume: true, conversationId }` runs the turn a
+ * `/confirm` answered `resume: true` for; a bare token whose confirmation
+ * resumes runs that turn on the same stream.
  */
 export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Promise<Response> {
   const origin = deps.corsOrigin ?? "*";
   const cors = corsHeaders(origin);
   const principal = await caller(req, deps, origin);
   if (principal instanceof Response) return principal;
-  let body: { text?: unknown; conversationId?: unknown; opening?: unknown };
+  let body: { text?: unknown; conversationId?: unknown; opening?: unknown; resume?: unknown };
   try {
     body = (await req.json()) as typeof body;
   } catch {
@@ -167,13 +170,18 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
   const opening = body.opening === true;
   // 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;
+  // The turn a `/confirm` answered `resume: true` for.
+  const resume = body.resume === true;
   if (opening && !named) {
     return Response.json({ ok: false, error: "an opening needs a conversationId" }, { status: 400, headers: cors });
   }
-  if (!opening && (typeof body.text !== "string" || body.text.trim().length === 0)) {
+  if (resume && !named) {
+    return Response.json({ ok: false, error: "a resumed turn needs a conversationId" }, { status: 400, headers: cors });
+  }
+  if (!opening && !resume && (typeof body.text !== "string" || body.text.trim().length === 0)) {
     return Response.json({ ok: false, error: "missing text" }, { status: 400, headers: cors });
   }
-  const text = opening ? "" : (body.text as string);
+  const text = opening || resume ? "" : (body.text as string);
   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 });
@@ -207,12 +215,14 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
 
       // Same deterministic interception as every other channel — a
       // previously-approved mutation must never depend on the model.
-      const confirmReply = opening ? null : await deps.confirm(text, sessionKey, principal);
-      if (confirmReply !== null) {
+      const confirmReply = opening || resume ? null : await deps.confirm(text, sessionKey, principal);
+      if (confirmReply !== null && confirmReply !== RESUME_AFTER_CONFIRM) {
         send("final", { text: confirmReply });
         close();
         return;
       }
+      // The confirmed action's result goes back to the model: the turn runs again, on this stream.
+      const resuming = resume || confirmReply === RESUME_AFTER_CONFIRM;
 
       const sink: TurnSink = {
         onToolStart: (label, detail, toolCallId, toolName) => send("tool", { label, detail, toolCallId, name: toolName }),
@@ -224,7 +234,7 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
         onReasoningEnd: (id, failed) => send("reasoning_end", { id, failed }),
         onStep: (step) => {
           const pending = detectPendingConfirmation(step);
-          if (pending) send("pending", { command: pending.summary, token: pending.token });
+          if (pending) send("pending", { command: pending.summary, token: pending.token, choices: pending.choices });
           const login = detectLoginRequired(step);
           if (login) send("login", { service: login.service, url: login.url });
         },
@@ -238,7 +248,7 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
           {
             channel: "http",
             multiUser: false,
-            text,
+            text: resuming ? "" : text,
             sessionKey,
             principal,
             // The caller's id comes from the auth provider, unchecked here.
@@ -246,6 +256,7 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
             abortSignal: abort.signal,
             ...(named ? { resume: deps.resumeMaxChars === undefined ? {} : { maxChars: deps.resumeMaxChars } } : {}),
             ...(opening ? { opening: true as const } : {}),
+            ...(resuming ? { resumeAfterConfirm: true as const } : {}),
           },
           sink,
         );
@@ -285,7 +296,9 @@ export type ConfirmRequestDeps = {
  * pending confirmation and its staged action was consumed and run; the `text`
  * then reports whether that execution succeeded. `resolved: false` means the
  * token was not a pending confirmation (unknown, expired, already used, or not
- * even token-shaped). Never touches the model.
+ * even token-shaped). `resume: true` (with no `text`) means the action handed
+ * its result back to the model: the client hears its answer by opening
+ * `/turn { resume: true, conversationId }`. Never touches the model.
  */
 export async function handleConfirmRequest(req: Request, deps: ConfirmRequestDeps): Promise<Response> {
   const origin = deps.corsOrigin ?? "*";
@@ -315,6 +328,9 @@ export async function handleConfirmRequest(req: Request, deps: ConfirmRequestDep
       return Response.json({ ok: true, resolved: true, text: `Confermato ed eseguito: ${JSON.stringify(outcome.data)}` }, { headers: cors });
     case "failed":
       return Response.json({ ok: true, resolved: true, text: `Confermato, ma l'esecuzione è fallita: ${outcome.error}` }, { headers: cors });
+    case "resume":
+      // The result went back to the model: the client opens `/turn { resume: true }` to hear its answer.
+      return Response.json({ ok: true, resolved: true, resume: true }, { headers: cors });
   }
 }
 

package/openapi.yaml

@@ -71,7 +71,16 @@ info:
     An irreversible action is never executed on the model's say-so: the turn
     emits a `pending` event carrying a one-time `token`. The client confirms by
     sending that token back — either as the `text` of a follow-up `POST /turn`,
-    or via `POST /confirm`.
+    or via `POST /confirm`. An action can offer several `choices` (e.g. "only
+    this time" / "always"), each with its own token: the caller sends back one,
+    and the others die with it.
+
+
+    Some actions hand their result back to the model instead of to the caller
+    (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.
 security:
   - bearerAuth: []
 servers:
@@ -85,7 +94,10 @@ paths:
         Runs one model turn and streams the result as `text/event-stream`. If
         `text` is a pending confirmation token it is resolved deterministically
         without ever consulting the model. Close the connection to cancel an
-        in-flight turn. With `opening: true` and no `text`, the assistant
+        in-flight turn. When the confirmation hands its result back to the
+        model, the model's answer to it streams instead. With `resume: true`
+        and no `text`, the turn is the one a `/confirm` answered `resume: true`
+        for. With `opening: true` and no `text`, the assistant
         speaks first in the conversation named (right after someone signs
         in): it does only for someone it doesn't know the name of, asking how
         to call them, and otherwise the stream carries a single `final` with
@@ -108,7 +120,8 @@ paths:
             An SSE stream. Each event is one of the types in `TurnEvent`:
             `reasoning`/`reasoning_end`, `text` (incremental deltas), `tool`/
             `tool_finish` (status of a tool call), `pending` (a staged
-            confirm-required action, with its command and token), `login` (a
+            confirm-required action, with its command, its token and the
+            choices it offers), `login` (a
             service the caller has to log in to first, with the link to open),
             `final` (the
             authoritative complete answer), and `error`.
@@ -117,7 +130,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/TurnEvent"
         "400":
-          description: Missing/invalid body, an opening without a conversationId, or a conversationId with characters outside the allowed ones.
+          description: Missing/invalid body, an opening or a resumed turn without a conversationId, or a conversationId with characters outside the allowed ones.
           content:
             application/json:
               schema:
@@ -146,7 +159,9 @@ paths:
           description: >
             `resolved: true` (with the reply `text`) when the token was a pending
             confirmation, `resolved: false` when it was not (unknown, expired, or
-            already used).
+            already used). `resolved: true` with `resume: true` and no `text`
+            when the action handed its result back to the model: the answer
+            comes from `POST /turn { resume: true, conversationId }`.
           content:
             application/json:
               schema:
@@ -552,11 +567,15 @@ components:
       properties:
         text:
           type: string
-          description: The user's message, or a bare confirmation token. Required, unless `opening` is true.
+          description: The user's message, or a bare confirmation token. Required, unless `opening` or `resume` is true.
         opening:
           type: boolean
           enum: [true]
           description: The assistant speaks first in `conversationId`, which is then required; `text` is ignored.
+        resume:
+          type: boolean
+          enum: [true]
+          description: The turn a `/confirm` answered `resume: true` for, in `conversationId`, which is then required; `text` is ignored.
         conversationId:
           type: string
           pattern: "^[A-Za-z0-9_-]{1,128}$"
@@ -594,7 +613,18 @@ components:
           description: On `pending` — the staged action's summary.
         token:
           type: string
-          description: On `pending` — the one-time confirmation token.
+          description: On `pending` — the one-time confirmation token (the first choice's).
+        choices:
+          type: array
+          description: On `pending` — every way to answer, in order; a plain staging has one, labelled `Conferma`.
+          items:
+            type: object
+            required: [token, label]
+            properties:
+              token:
+                type: string
+              label:
+                type: string
         service:
           type: string
           description: On `login` — the service the caller has to log in to.
@@ -626,7 +656,11 @@ components:
           type: boolean
         text:
           type: string
-          description: The confirmation reply, present when `resolved` is true.
+          description: The confirmation reply, present when `resolved` is true and `resume` isn't.
+        resume:
+          type: boolean
+          enum: [true]
+          description: The action handed its result back to the model; its answer comes from `POST /turn { resume: true, conversationId }`.
     Message:
       type: object
       required: [role, content, timestamp]

package/package.json

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