@mercury-fw/channel-http 0.14.2 → 0.15.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @mercury-fw/channel-http
 
+## 0.15.1
+
+### Patch Changes
+
+- 9e2fbe4: - the verbatim archive keeps, with each answer, what its turn showed besides the text, as `trace`: reasoning blocks, tool status lines with their outcome, confirmations staged, logins asked for (no tokens, no login links)
+  - a stopped turn's interrupted answer keeps its `trace` up to the stop
+  - an answer that only staged an action keeps its `pendingNote`
+  - a resolved confirmation is archived in its conversation as a message with `confirmation: { id, status, choice? }`, its `content` the reply the person got
+  - `GET /conversation` returns `trace`, `pendingNote` and `confirmation`; `recall_verbatim` and a conversation rebuilt from the archive leave them out
+  - `ConfirmDeps.onResolved` (`@mercury-fw/confirm-engine`): told how a staged action was resolved
+  - `openapi.yaml`: `Message.trace`, `Message.pendingNote`, `Message.confirmation`, `TraceEntry`
+
+## 0.15.0
+
+### Minor Changes
+
+- 148417b: - a step whose tool asks the person to log in ends the turn: no further tool calls
+  - the turn's text closes with `core.login.note`, naming the services to log in to (`core.login.note-any` when none has a name)
+  - `detectLoginRequests(step)` in `@mercury-fw/channel-types`: every login a step asks for, one per link
+  - HTTP channel: one `login` event per service the step asks for
+  - Google Chat: one login card per service the step asks for
+  - **Migration:** apps with their own locale files add `core.login.note` (`{services}`) and `core.login.note-any` to each non-English one
+
 ## 0.14.2
 
 ### Patch Changes

package/README.md

@@ -72,7 +72,7 @@ Reasoning and answer text arrive as **incremental deltas** — never one finishe
 | `tool_finish` | `{ toolCallId, outcome }` | a tool call settles (`outcome`: `success` \| `failed` \| `pending`) |
 | `text` | `{ chunk }` | an answer-text delta |
 | `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, each label in the caller's language; one with an empty `label` for a plain staging, which the UI words itself, a "Confirm" button): 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) |
+| `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). One per service; the turn ends after the step that asked, its `final` text telling them to log in and write again |
 | `final` | `{ text, pendingNote? }` | the complete answer (also emitted for a token confirmation, with no model turn). `pendingNote` is there when the model wrote nothing because the turn staged an action: the core's stand-in sentence `text` begins with (then any list the turn surfaced). A UI showing its own confirmation hides it; the conversation's transcript keeps it |
 | `error` | `{ message }` | the turn failed mid-stream |
 
@@ -107,7 +107,7 @@ All `GET`, all JSON, all reporting state already held in-process. They need an a
 
 | endpoint | `data` on success |
 |---|---|
-| `GET /conversation?id=<conversationId>&limit=<n>&offset=<cursor>` | `{ messages: [{ role, content, interrupted?, timestamp }], nextOffset }` — one of your conversations, its durable transcript in order, each answer as you saw it with the lists it showed (empty for an id that isn't yours). An answer whose turn was cancelled has `interrupted: true` and an empty `content`: the question before it was left unanswered. `400` if `id` is missing or has other characters than `/turn` accepts |
+| `GET /conversation?id=<conversationId>&limit=<n>&offset=<cursor>` | `{ messages: [{ role, content, interrupted?, trace?, pendingNote?, confirmation?, timestamp }], nextOffset }` — one of your conversations, its durable transcript in order, each answer as you saw it with the lists it showed (empty for an id that isn't yours). An answer whose turn was cancelled has `interrupted: true` and an empty `content`: the question before it was left unanswered. An answer's `trace` is what its turn showed besides the text, in order, as the events above showed it: each reasoning block in full, each status line with its tool and outcome, each confirmation staged (its command and its choices' labels, named by an `id`, never a token), each login asked for (its service, never the link); up to the stop for a cancelled turn. `pendingNote` is the turn's `final` one. A message with `confirmation: { id, status, choice? }` says how the staged action with that `id` (its trace entry) was resolved (`ok`, `failed`, or `resume`, whose answer is the next message): its `content` is the reply you got, empty for `resume`. Answers archived before these fields have none of them. `400` if `id` is missing or has other characters than `/turn` accepts |
 | `GET /conversations?limit=<n>` | `{ conversations: [{ conversationId, lastTimestamp, preview }] }` — your conversations, most-recently-active first; the preview is the newest message that shows something, so the question when the last answer was interrupted |
 | `GET /manifest` | `{ manifest: { coreApiVersion, plugins: [{ name, apiVersion, active, skills, hasBuild, customStatus }], activeClis, skills } }` |
 | `GET /confirmations` | `{ pending: [{ sessionKey, summary, expiresAt }] }` — your pending confirmations; tokens are deliberately never included |

package/http-server.ts

@@ -23,7 +23,7 @@
  * package never imports the app.
  */
 import {
-  detectLoginRequired,
+  detectLoginRequests,
   detectPendingConfirmation,
   type HandleTurn,
   type TurnSink,
@@ -262,8 +262,7 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
         onStep: (step) => {
           const pending = detectPendingConfirmation(step);
           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 });
+          for (const login of detectLoginRequests(step)) send("login", { service: login.service, url: login.url });
         },
         onUsage: () => {},
         // The core says when the text is its stand-in for an answer the

package/openapi.yaml

@@ -132,7 +132,8 @@ paths:
             `tool_finish` (status of a tool call), `pending` (a staged
             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),
+            service the caller has to log in to first, with the link to open;
+            one per service, and the turn ends after the step that asked),
             `final` (the
             authoritative complete answer), and `error`.
           headers:
@@ -261,7 +262,7 @@ paths:
         "503":
           $ref: "#/components/responses/NotAdmitted"
         "200":
-          description: The conversation's messages in chronological order; none when it isn't one of the caller's.
+          description: The conversation's messages in chronological order, each answer with what its turn showed besides the text; none when it isn't one of the caller's.
           content:
             application/json:
               schema:
@@ -829,9 +830,93 @@ components:
           type: boolean
           enum: [true]
           description: "On an answer whose turn was stopped before it was finished (the client closed the stream): `content` is empty. The question before it was left unanswered."
+        trace:
+          type: array
+          description: >
+            On an answer: what the person saw of the turn besides its text, in
+            the order it happened, as the turn's events showed it (up to the
+            stop, for an interrupted one). Absent when there was nothing, and
+            on answers archived before it was kept.
+          items:
+            $ref: "#/components/schemas/TraceEntry"
+        pendingNote:
+          type: string
+          description: >
+            On an answer whose model wrote nothing because the turn staged an
+            action: the core's stand-in sentence `content` begins with, as the
+            turn's `final` event gave it. A UI showing the confirmation from
+            the trace hides it.
+        confirmation:
+          type: object
+          description: >
+            On the message saying how a staged action was resolved (a token
+            sent back, a choice clicked): `content` is the reply the person
+            got, empty when the confirmed action's result went back to the
+            model (`resume`), whose answer is the next message. `id` is the
+            one of the trace's `confirmation` entry it resolves, which says
+            what the action was.
+          required: [id, status]
+          properties:
+            id:
+              type: string
+            status:
+              type: string
+              enum: [ok, failed, resume]
+            choice:
+              type: string
+              description: The label of the choice taken, when the action was offered as several.
         timestamp:
           type: string
           description: ISO 8601, millisecond precision — the durable ordering key.
+    TraceEntry:
+      type: object
+      description: >
+        One thing a turn showed besides its text. `reasoning`: a reasoning
+        block in full, `failed` when it was cut. `tool`: a status line, with
+        the tool the model called (`name`, absent for Mercury's own lines) and
+        how it went (`outcome`, absent when it never finished). `confirmation`:
+        an action staged, with the labels of its choices (one empty label for a
+        plain confirmation); `id` names it, never its token. `login`: a login
+        asked for, by service, never its link.
+      required: [type]
+      properties:
+        type:
+          type: string
+          enum: [reasoning, tool, confirmation, login]
+        text:
+          type: string
+          description: On `reasoning`.
+        failed:
+          type: boolean
+          enum: [true]
+          description: On `reasoning`.
+        label:
+          type: string
+          description: On `tool`.
+        detail:
+          type: string
+          description: On `tool`.
+        name:
+          type: string
+          description: On `tool`.
+        outcome:
+          type: string
+          enum: [success, failed, pending]
+          description: On `tool`.
+        id:
+          type: string
+          description: On `confirmation`.
+        command:
+          type: string
+          description: On `confirmation`.
+        choices:
+          type: array
+          items:
+            type: string
+          description: On `confirmation`.
+        service:
+          type: string
+          description: On `login`.
     ConversationPage:
       type: object
       required: [ok, messages]

package/package.json

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