@mhome/conversation-protocol 3.6.1 → 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
@@ -11,6 +11,16 @@ contains no Agent runtime, persistence, transport implementation, or messaging-p
 threads themselves. The Conversation implementation owns active-thread creation, idle rotation,
 pending-interaction policy, idempotency, and enqueueing for that operation.
 
+Each newly created `ThreadSummary` carries a durable `origin`: either
+`{ "type": "turn", "requestId": "…" }` for creation/idle rotation caused by
+`turn/submit`, or `{ "type": "operation", "operationId": "…" }` for an explicit
+thread/session operation. The owner assigns it when committing creation; callers
+cannot supply it as request metadata. It is immutable and appears in control,
+catalog and thread-load projections, including queries after reconnection.
+It identifies creation, not turn admission or execution. Origin can be absent
+for records written before tracking was introduced; clients must not infer a
+cause from operation-ID spelling, timing or the presence of an unbound send.
+
 The canonical `cs1` surface families are client personal (`cp`), client group (`cg`), messaging
 personal (`mp`), and messaging group (`mg`). Messaging surfaces include provider, provider account,
 external conversation, and an optional lane. A lane isolates a provider sub-conversation such as a
@@ -70,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/control-get.response.json

@@ -11,7 +11,11 @@
       "createdAt": "2026-08-22T00:00:00Z",
       "updatedAt": "2026-08-22T00:00:00Z",
       "archivedAt": null,
-      "purgeAfter": null
+      "purgeAfter": null,
+      "origin": {
+        "type": "operation",
+        "operationId": "session-start-2"
+      }
     },
     "activeRun": null,
     "pendingInteraction": null,

package/fixtures/control.event.json

@@ -14,7 +14,11 @@
         "createdAt": "2026-08-22T00:00:00Z",
         "updatedAt": "2026-08-22T00:00:00Z",
         "archivedAt": null,
-        "purgeAfter": null
+        "purgeAfter": null,
+        "origin": {
+          "type": "turn",
+          "requestId": "turn-create-2"
+        }
       },
       "activeRun": null,
       "pendingInteraction": null,

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.6.1",
+  "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.6.1",
+  "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.6.1",
+  "contractVersion": "3.8.0",
   "manifest": "manifest/targets.v1.json",
   "schemas": {
     "frame": "schema/conversation-frame.v2.schema.json",

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

@@ -382,6 +382,9 @@
               "type": "null"
             }
           ]
+        },
+        "origin": {
+          "$ref": "#/$defs/threadOrigin"
         }
       }
     },
@@ -1572,6 +1575,15 @@
         },
         {
           "$ref": "#/$defs/catalogCommandResponse"
+        },
+        {
+          "$ref": "#/$defs/updateRequest"
+        },
+        {
+          "$ref": "#/$defs/statusRequest"
+        },
+        {
+          "$ref": "#/$defs/statusResponse"
         }
       ]
     },
@@ -1914,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"
+                }
+              ]
             }
           }
         }
@@ -2214,7 +2232,10 @@
       ],
       "properties": {
         "target": {
-          "const": "/chat/queue/reorder"
+          "enum": [
+            "/chat/queue/reorder",
+            "/chat/queue/update"
+          ]
         },
         "direction": {
           "const": "response"
@@ -2228,7 +2249,7 @@
           ],
           "properties": {
             "receipt": {
-              "$ref": "#/$defs/queue"
+              "$ref": "#/$defs/queueMutationReceipt"
             },
             "control": {
               "oneOf": [
@@ -2817,6 +2838,180 @@
           }
         }
       }
+    },
+    "threadOrigin": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "type",
+            "requestId"
+          ],
+          "properties": {
+            "type": {
+              "const": "turn"
+            },
+            "requestId": {
+              "$ref": "#/$defs/id"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "type",
+            "operationId"
+          ],
+          "properties": {
+            "type": {
+              "const": "operation"
+            },
+            "operationId": {
+              "$ref": "#/$defs/id"
+            }
+          }
+        }
+      ]
+    },
+    "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"
+                }
+              ]
+            }
+          }
+        }
+      }
     }
   }
 }