@mhome/conversation-protocol 3.7.0 → 3.8.0

package/README.md

@@ -1,6 +1,6 @@
 # mhome-conversation-api
 
-Typed, transport-neutral DTOs and canonical surface identities for the mHome conversation API.
+Typed, transport-neutral DTOs and canonical surface identities for the MeowLink conversation API.
 
 This crate owns wire targets, request and response bodies, user-visible message content, and
 conversation events. `ConversationSurface` is a canonical value object whose string form is the
@@ -80,3 +80,30 @@ Final replies, failures, cancellations, queue state, and actionable user
 confirmations remain durable. Snapshot deltas keep their existing contiguous
 version/recovery rules. Agent checkpoints and billing are independent of live
 presentation delivery.
+
+## Waiting queue operations
+
+`/chat/queue/update` replaces the complete content of one waiting request. Its
+request ID, original admission fingerprint, author, and frozen execution settings
+remain unchanged. Concurrent edits use the last successful server commit; client
+clocks are irrelevant. Claiming the request for execution and editing it share the
+same transactional boundary, so an edit cannot succeed after execution begins.
+
+`/chat/queue/reorder` moves `requestId` before `beforeRequestId`; a null anchor
+moves it to the tail. The server applies the move to its current queue, preserving
+new arrivals and unrelated moves. A missing request or anchor is a conflict; a
+client must never replace the whole queue from its stale local list.
+
+Both operations require an `operationId`, scoped to the surface and request ID.
+An exact retry returns `already_applied` and the original operation's queue version,
+without replaying its changes. Reusing it with another payload is a conflict.
+Command responses still carry a fresh authoritative control projection; clients
+apply control versions monotonically rather than treating a mutation receipt as
+a queue snapshot. Events and command responses use the same control versions.
+
+Cancellation, including archive cleanup, retains a durable terminal admission
+receipt independently of transcript retention. `/chat/request/status` reads that
+receipt by request ID, returning null admission for an unknown request. It recovers
+missed `admission.changed` events without reenqueuing or guessing from an empty
+queue. Retry of the original submission still checks its original content, even
+when the queued execution content was later edited.

package/fixtures/queue-reorder.request.json

@@ -3,7 +3,8 @@
   "direction": "request",
   "body": {
     "threadId": "thread-2",
-    "expectedQueueVersion": 3,
-    "orderedRequestIds": ["request-2", "request-1"]
+    "requestId": "request-2",
+    "operationId": "move-1",
+    "beforeRequestId": "request-1"
   }
 }

package/fixtures/queue-reorder.response.json

@@ -3,8 +3,10 @@
   "direction": "response",
   "body": {
     "receipt": {
+      "operationId": "move-1",
+      "requestId": "request-2",
       "queueVersion": 4,
-      "items": []
+      "disposition": "applied"
     },
     "control": {
       "surfaceId": "cs1:cp:dXNlcg",

package/fixtures/queue-update.request.json

@@ -0,0 +1,17 @@
+{
+  "target": "/chat/queue/update",
+  "direction": "request",
+  "body": {
+    "threadId": "thread-2",
+    "requestId": "request-2",
+    "operationId": "edit-1",
+    "content": {
+      "parts": [
+        {
+          "type": "text",
+          "text": "Updated instruction"
+        }
+      ]
+    }
+  }
+}

package/fixtures/queue-update.response.json

@@ -0,0 +1,32 @@
+{
+  "target": "/chat/queue/update",
+  "direction": "response",
+  "body": {
+    "receipt": {
+      "operationId": "edit-1",
+      "requestId": "request-2",
+      "queueVersion": 4,
+      "disposition": "applied"
+    },
+    "control": {
+      "surfaceId": "cs1:cp:dXNlcg",
+      "version": "00000000000000000001:00000000000000000001",
+      "activeThread": {
+        "threadId": "thread-2",
+        "title": "New conversation",
+        "state": "active",
+        "createdAt": "2026-08-22T00:00:00Z",
+        "updatedAt": "2026-08-22T00:00:00Z",
+        "archivedAt": null,
+        "purgeAfter": null
+      },
+      "activeRun": null,
+      "pendingInteraction": null,
+      "queue": {
+        "queueVersion": 0,
+        "items": []
+      },
+      "historyVersion": 0
+    }
+  }
+}

package/fixtures/request-status.request.json

@@ -0,0 +1,7 @@
+{
+  "target": "/chat/request/status",
+  "direction": "request",
+  "body": {
+    "requestId": "request-2"
+  }
+}

package/fixtures/request-status.response.json

@@ -0,0 +1,14 @@
+{
+  "target": "/chat/request/status",
+  "direction": "response",
+  "body": {
+    "requestId": "request-2",
+    "admission": {
+      "state": "cancelled",
+      "admissionVersion": 2,
+      "reason": "cancelled",
+      "threadId": "thread-2",
+      "queueVersion": 5
+    }
+  }
+}

package/manifest/targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.conversation.targets.v1",
-  "contractVersion": "3.7.0",
+  "contractVersion": "3.8.0",
   "requestTargets": [
     "/chat/control/get",
     "/chat/thread/list",
@@ -14,7 +14,9 @@
     "/chat/interaction/answer",
     "/chat/queue/reorder",
     "/chat/request/cancel",
-    "/chat/interaction/submit"
+    "/chat/interaction/submit",
+    "/chat/queue/update",
+    "/chat/request/status"
   ],
   "eventTargets": [
     "/chat/event",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mhome/conversation-protocol",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "Build-time protocol artifacts for mhome.conversation",
   "license": "MIT",
   "repository": {

package/protocol.json

@@ -1,6 +1,6 @@
 {
   "protocol": "mhome.conversation",
-  "contractVersion": "3.7.0",
+  "contractVersion": "3.8.0",
   "manifest": "manifest/targets.v1.json",
   "schemas": {
     "frame": "schema/conversation-frame.v2.schema.json",

package/schema/conversation-frame.v2.schema.json

@@ -1575,6 +1575,15 @@
         },
         {
           "$ref": "#/$defs/catalogCommandResponse"
+        },
+        {
+          "$ref": "#/$defs/updateRequest"
+        },
+        {
+          "$ref": "#/$defs/statusRequest"
+        },
+        {
+          "$ref": "#/$defs/statusResponse"
         }
       ]
     },
@@ -1917,23 +1926,29 @@
           "additionalProperties": false,
           "required": [
             "threadId",
-            "expectedQueueVersion",
-            "orderedRequestIds"
+            "requestId",
+            "operationId",
+            "beforeRequestId"
           ],
           "properties": {
             "threadId": {
               "$ref": "#/$defs/id"
             },
-            "expectedQueueVersion": {
-              "type": "integer",
-              "minimum": 0
+            "requestId": {
+              "$ref": "#/$defs/id"
             },
-            "orderedRequestIds": {
-              "type": "array",
-              "uniqueItems": true,
-              "items": {
-                "$ref": "#/$defs/id"
-              }
+            "operationId": {
+              "$ref": "#/$defs/id"
+            },
+            "beforeRequestId": {
+              "oneOf": [
+                {
+                  "$ref": "#/$defs/id"
+                },
+                {
+                  "type": "null"
+                }
+              ]
             }
           }
         }
@@ -2217,7 +2232,10 @@
       ],
       "properties": {
         "target": {
-          "const": "/chat/queue/reorder"
+          "enum": [
+            "/chat/queue/reorder",
+            "/chat/queue/update"
+          ]
         },
         "direction": {
           "const": "response"
@@ -2231,7 +2249,7 @@
           ],
           "properties": {
             "receipt": {
-              "$ref": "#/$defs/queue"
+              "$ref": "#/$defs/queueMutationReceipt"
             },
             "control": {
               "oneOf": [
@@ -2856,6 +2874,144 @@
           }
         }
       ]
+    },
+    "updateRequest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "target",
+        "direction",
+        "body"
+      ],
+      "properties": {
+        "target": {
+          "const": "/chat/queue/update"
+        },
+        "direction": {
+          "const": "request"
+        },
+        "body": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "threadId",
+            "requestId",
+            "operationId",
+            "content"
+          ],
+          "properties": {
+            "threadId": {
+              "$ref": "#/$defs/id"
+            },
+            "requestId": {
+              "$ref": "#/$defs/id"
+            },
+            "operationId": {
+              "$ref": "#/$defs/id"
+            },
+            "content": {
+              "$ref": "#/$defs/content"
+            }
+          }
+        }
+      }
+    },
+    "queueMutationReceipt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "operationId",
+        "requestId",
+        "queueVersion",
+        "disposition"
+      ],
+      "properties": {
+        "operationId": {
+          "$ref": "#/$defs/id"
+        },
+        "requestId": {
+          "$ref": "#/$defs/id"
+        },
+        "queueVersion": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "disposition": {
+          "enum": [
+            "applied",
+            "already_applied"
+          ]
+        }
+      }
+    },
+    "statusRequest": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "target",
+        "direction",
+        "body"
+      ],
+      "properties": {
+        "target": {
+          "const": "/chat/request/status"
+        },
+        "direction": {
+          "const": "request"
+        },
+        "body": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "requestId"
+          ],
+          "properties": {
+            "requestId": {
+              "$ref": "#/$defs/id"
+            }
+          }
+        }
+      }
+    },
+    "statusResponse": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "target",
+        "direction",
+        "body"
+      ],
+      "properties": {
+        "target": {
+          "const": "/chat/request/status"
+        },
+        "direction": {
+          "const": "response"
+        },
+        "body": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "requestId",
+            "admission"
+          ],
+          "properties": {
+            "requestId": {
+              "$ref": "#/$defs/id"
+            },
+            "admission": {
+              "oneOf": [
+                {
+                  "$ref": "#/$defs/requestAdmission"
+                },
+                {
+                  "type": "null"
+                }
+              ]
+            }
+          }
+        }
+      }
     }
   }
 }