@mercury-fw/channel-http 0.15.0 → 0.15.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @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

package/README.md

@@ -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/openapi.yaml

@@ -262,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:
@@ -830,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.15.0",
+  "version": "0.15.1",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -21,8 +21,8 @@
     "@mercury-fw/channel-types": ">=0.68.0 <1.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-types": "0.68.0",
-    "@mercury-fw/plugin-types": "0.68.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"