@mhome/conversation-protocol 0.11.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) MHOME AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# mhome-conversation-api
+
+Typed, transport-neutral DTOs and canonical surface identities for the mHome 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
+wire and persistence identity of one isolated conversation endpoint. The crate deliberately
+contains no Agent runtime, persistence, transport implementation, or messaging-provider SDK.
+
+`/chat/turn/submit` is the source-neutral application operation for callers that do not manage
+threads themselves. The Conversation implementation owns active-thread creation, idle rotation,
+pending-interaction policy, idempotency, and enqueueing for that operation.
+
+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
+Telegram forum topic without changing the provider account's base authorization route.
+
+Message content is a provider-independent ordered list of text, image, audio, video, and file parts.
+Messaging runtimes must materialize provider media handles into this content before invoking the
+Conversation application port; the Agent and this contract never receive provider SDK objects.

package/fixtures/catalog.event.json

@@ -0,0 +1,16 @@
+{
+  "target": "/chat/event",
+  "direction": "event",
+  "body": {
+    "type": "thread.catalog_changed",
+    "surfaceId": "cs1:cp:dXNlci0x",
+    "catalogVersion": 2,
+    "occurredAt": "2026-08-22T00:00:00Z",
+    "data": {
+      "activeThreadId": "thread-2",
+      "threads": [
+        { "threadId": "thread-2", "title": "New conversation", "state": "active", "createdAt": "2026-08-22T00:00:00Z", "updatedAt": "2026-08-22T00:00:00Z", "archivedAt": null, "purgeAfter": null }
+      ]
+    }
+  }
+}

package/fixtures/debug.event.json

@@ -0,0 +1,17 @@
+{
+  "target": "/chat/debug",
+  "direction": "event",
+  "body": {
+    "type": "run.debug",
+    "surfaceId": "cs1:cp:dXNlci0x",
+    "threadId": "thread-1",
+    "requestId": "request-1",
+    "occurredAt": "2026-08-22T00:00:01Z",
+    "data": {
+      "scope": "llm.request",
+      "payload": {
+        "model": "logical-model"
+      }
+    }
+  }
+}

package/fixtures/enqueue.request.json

@@ -0,0 +1,26 @@
+{
+  "target": "/chat/message/enqueue",
+  "direction": "request",
+  "body": {
+    "threadId": "thread-2",
+    "requestId": "request-1",
+    "content": {
+      "parts": [
+        { "type": "text", "text": "Hello" },
+        {
+          "type": "image",
+          "source": { "kind": "artifact", "uri": "artifact://image-1" },
+          "mime_type": "image/png",
+          "width_px": 640,
+          "height_px": 480,
+          "size_bytes": 1024
+        }
+      ]
+    },
+    "accessMode": "interactive",
+    "agentModelMode": "auto",
+    "temperature": 0.2,
+    "allowTools": true,
+    "debug": false
+  }
+}

package/fixtures/enqueue.response.json

@@ -0,0 +1,9 @@
+{
+  "target": "/chat/message/enqueue",
+  "direction": "response",
+  "body": {
+    "requestId": "request-1",
+    "disposition": "queued",
+    "queueVersion": 4
+  }
+}

package/fixtures/interaction-answer.request.json

@@ -0,0 +1,12 @@
+{
+  "target": "/chat/interaction/answer",
+  "direction": "request",
+  "body": {
+    "requestId": "request-1",
+    "batchId": "batch-1",
+    "decisions": [
+      { "actionId": "action-1", "decision": "approve" }
+    ],
+    "occurredAtUnixMs": 1787587200000
+  }
+}

package/fixtures/interaction-answer.response.json

@@ -0,0 +1,9 @@
+{
+  "target": "/chat/interaction/answer",
+  "direction": "response",
+  "body": {
+    "requestId": "request-1",
+    "threadId": "thread-3",
+    "disposition": "accepted"
+  }
+}

package/fixtures/interaction.event.json

@@ -0,0 +1,39 @@
+{
+  "target": "/chat/event",
+  "direction": "event",
+  "body": {
+    "type": "snapshot.updated",
+    "surfaceId": "cs1:mg:feishu:YWNjb3VudA:Y2hhdA",
+    "threadId": "thread-2",
+    "requestId": "request-1",
+    "snapshotVersion": 3,
+    "occurredAt": "2026-08-22T00:00:00Z",
+    "data": {
+      "sessionActivityAtUnixMs": 1787356800000,
+      "messagesAdded": [],
+      "activeRun": null,
+      "pendingInteraction": {
+        "requestId": "request-1",
+        "batchId": "batch-1",
+        "title": "Delete room",
+        "message": "Delete room Kitchen",
+        "items": [
+          {
+            "actionId": "action-1",
+            "kind": "approval",
+            "preview": {
+              "actionCode": "room.delete",
+              "title": "Delete room",
+              "message": "Delete room Kitchen",
+              "tone": "danger",
+              "details": [{ "label": "Room", "value": { "type": "text", "text": "Kitchen" } }],
+              "proceedLabel": "Delete",
+              "rejectLabel": "Cancel"
+            }
+          }
+        ]
+      },
+      "runOutcome": { "requestId": "request-1", "status": "interaction_required", "failure": null }
+    }
+  }
+}

package/fixtures/interaction.request.json

@@ -0,0 +1,11 @@
+{
+  "target": "/chat/interaction/submit",
+  "direction": "request",
+  "body": {
+    "threadId": "thread-2",
+    "batchId": "batch-1",
+    "decisions": [
+      { "actionId": "action-1", "decision": "approve" }
+    ]
+  }
+}

package/fixtures/interaction.response.json

@@ -0,0 +1,8 @@
+{
+  "target": "/chat/interaction/submit",
+  "direction": "response",
+  "body": {
+    "requestId": "request-1",
+    "disposition": "accepted"
+  }
+}

package/fixtures/live.event.json

@@ -0,0 +1,14 @@
+{
+  "target": "/chat/event",
+  "direction": "event",
+  "body": {
+    "type": "assistant.preview",
+    "surfaceId": "cs1:mg:feishu:YWNjb3VudA:Y2hhdA",
+    "threadId": "thread-1",
+    "requestId": "request-1",
+    "baseSnapshotVersion": 3,
+    "offset": 1,
+    "occurredAt": "2026-08-22T00:00:00Z",
+    "data": { "text": "Working", "append": true }
+  }
+}

package/fixtures/progress-planning.event.json

@@ -0,0 +1,14 @@
+{
+  "target": "/chat/event",
+  "direction": "event",
+  "body": {
+    "type": "run.progress",
+    "surfaceId": "cs1:cp:dXNlci0x",
+    "threadId": "thread-1",
+    "requestId": "request-1",
+    "baseSnapshotVersion": 3,
+    "offset": 3,
+    "occurredAt": "2026-08-22T00:00:02Z",
+    "data": { "kind": "planning" }
+  }
+}

package/fixtures/progress-thinking.event.json

@@ -0,0 +1,14 @@
+{
+  "target": "/chat/event",
+  "direction": "event",
+  "body": {
+    "type": "run.progress",
+    "surfaceId": "cs1:cp:dXNlci0x",
+    "threadId": "thread-1",
+    "requestId": "request-1",
+    "baseSnapshotVersion": 3,
+    "offset": 2,
+    "occurredAt": "2026-08-22T00:00:01Z",
+    "data": { "kind": "thinking" }
+  }
+}

package/fixtures/progress-tool-scheduled.event.json

@@ -0,0 +1,14 @@
+{
+  "target": "/chat/event",
+  "direction": "event",
+  "body": {
+    "type": "run.progress",
+    "surfaceId": "cs1:cp:dXNlci0x",
+    "threadId": "thread-1",
+    "requestId": "request-1",
+    "baseSnapshotVersion": 3,
+    "offset": 5,
+    "occurredAt": "2026-08-22T00:00:04Z",
+    "data": { "kind": "tool_scheduled", "toolNames": ["search", "fetch"] }
+  }
+}

package/fixtures/progress-tool-started.event.json

@@ -0,0 +1,14 @@
+{
+  "target": "/chat/event",
+  "direction": "event",
+  "body": {
+    "type": "run.progress",
+    "surfaceId": "cs1:cp:dXNlci0x",
+    "threadId": "thread-1",
+    "requestId": "request-1",
+    "baseSnapshotVersion": 3,
+    "offset": 6,
+    "occurredAt": "2026-08-22T00:00:05Z",
+    "data": { "kind": "tool_started", "toolName": "search" }
+  }
+}

package/fixtures/progress-waiting.event.json

@@ -0,0 +1,14 @@
+{
+  "target": "/chat/event",
+  "direction": "event",
+  "body": {
+    "type": "run.progress",
+    "surfaceId": "cs1:cp:dXNlci0x",
+    "threadId": "thread-1",
+    "requestId": "request-1",
+    "baseSnapshotVersion": 3,
+    "offset": 4,
+    "occurredAt": "2026-08-22T00:00:03Z",
+    "data": { "kind": "waiting_external" }
+  }
+}

package/fixtures/queue-reorder.request.json

@@ -0,0 +1,9 @@
+{
+  "target": "/chat/queue/reorder",
+  "direction": "request",
+  "body": {
+    "threadId": "thread-2",
+    "expectedQueueVersion": 3,
+    "orderedRequestIds": ["request-2", "request-1"]
+  }
+}

package/fixtures/queue-reorder.response.json

@@ -0,0 +1,8 @@
+{
+  "target": "/chat/queue/reorder",
+  "direction": "response",
+  "body": {
+    "queueVersion": 4,
+    "items": []
+  }
+}

package/fixtures/queue.event.json

@@ -0,0 +1,12 @@
+{
+  "target": "/chat/event",
+  "direction": "event",
+  "body": {
+    "type": "queue.changed",
+    "surfaceId": "cs1:mg:feishu:YWNjb3VudA:Y2hhdA",
+    "threadId": "thread-1",
+    "queueVersion": 4,
+    "occurredAt": "2026-08-22T00:00:00Z",
+    "data": { "items": [], "activeRun": null }
+  }
+}

package/fixtures/request-cancel.request.json

@@ -0,0 +1,8 @@
+{
+  "target": "/chat/request/cancel",
+  "direction": "request",
+  "body": {
+    "threadId": "thread-2",
+    "requestId": "request-1"
+  }
+}

package/fixtures/request-cancel.response.json

@@ -0,0 +1,10 @@
+{
+  "target": "/chat/request/cancel",
+  "direction": "response",
+  "body": {
+    "requestId": "request-1",
+    "phase": "running",
+    "outcome": "cancelling",
+    "queueVersion": 4
+  }
+}

package/fixtures/session-start.request.json

@@ -0,0 +1,8 @@
+{
+  "target": "/chat/session/start",
+  "direction": "request",
+  "body": {
+    "operationId": "operation-2",
+    "reason": "user_requested"
+  }
+}

package/fixtures/session-start.response.json

@@ -0,0 +1,16 @@
+{
+  "target": "/chat/session/start",
+  "direction": "response",
+  "body": {
+    "operationId": "operation-2",
+    "threadId": "thread-3",
+    "disposition": "rotated",
+    "catalog": {
+      "catalogVersion": 4,
+      "activeThreadId": "thread-3",
+      "threads": [
+        { "threadId": "thread-3", "title": "New conversation", "state": "active", "createdAt": "2026-08-22T02:00:00Z", "updatedAt": "2026-08-22T02:00:00Z", "archivedAt": null, "purgeAfter": null }
+      ]
+    }
+  }
+}

package/fixtures/session.event.json

@@ -0,0 +1,11 @@
+{
+  "target": "/chat/event",
+  "direction": "event",
+  "body": {
+    "type": "session.policy_changed",
+    "version": 2,
+    "surfaceId": "cs1:mg:feishu:YWNjb3VudA:Y2hhdA",
+    "occurredAt": "2026-08-22T00:00:00Z",
+    "data": { "idleTimeoutMinutes": 60, "updatedAtMs": 1787356800000 }
+  }
+}

package/fixtures/system-failed.event.json

@@ -0,0 +1,14 @@
+{
+  "target": "/chat/event",
+  "direction": "event",
+  "body": {
+    "type": "run.system_failed",
+    "surfaceId": "cs1:cp:dXNlci0x",
+    "threadId": "thread-1",
+    "requestId": "request-1",
+    "baseSnapshotVersion": 3,
+    "offset": 7,
+    "occurredAt": "2026-08-22T00:00:06Z",
+    "data": { "code": "AGENT_UNAVAILABLE", "message": "Agent connection was lost" }
+  }
+}

package/fixtures/thread-archive.request.json

@@ -0,0 +1,8 @@
+{
+  "target": "/chat/thread/archive",
+  "direction": "request",
+  "body": {
+    "threadId": "thread-1",
+    "expectedCatalogVersion": 3
+  }
+}

package/fixtures/thread-archive.response.json

@@ -0,0 +1,11 @@
+{
+  "target": "/chat/thread/archive",
+  "direction": "response",
+  "body": {
+    "catalogVersion": 3,
+    "activeThreadId": null,
+    "threads": [
+      { "threadId": "thread-2", "title": "New conversation", "state": "archived", "createdAt": "2026-08-22T00:00:00Z", "updatedAt": "2026-08-22T01:00:00Z", "archivedAt": "2026-08-22T01:00:00Z", "archiveReason": "user_requested", "purgeAfter": "2026-08-25T01:00:00Z" }
+    ]
+  }
+}

package/fixtures/thread-create.request.json

@@ -0,0 +1,9 @@
+{
+  "target": "/chat/thread/create",
+  "direction": "request",
+  "body": {
+    "operationId": "operation-1",
+    "expectedCatalogVersion": 1,
+    "title": "New conversation"
+  }
+}

package/fixtures/thread-create.response.json

@@ -0,0 +1,11 @@
+{
+  "target": "/chat/thread/create",
+  "direction": "response",
+  "body": {
+    "catalogVersion": 2,
+    "activeThreadId": "thread-2",
+    "threads": [
+      { "threadId": "thread-2", "title": "New conversation", "state": "active", "createdAt": "2026-08-22T00:00:00Z", "updatedAt": "2026-08-22T00:00:00Z", "archivedAt": null, "purgeAfter": null }
+    ]
+  }
+}

package/fixtures/thread-list.request.json

@@ -0,0 +1,5 @@
+{
+  "target": "/chat/thread/list",
+  "direction": "request",
+  "body": {}
+}

package/fixtures/thread-list.response.json

@@ -0,0 +1,12 @@
+{
+  "target": "/chat/thread/list",
+  "direction": "response",
+  "body": {
+    "catalogVersion": 2,
+    "activeThreadId": "thread-2",
+    "threads": [
+      { "threadId": "thread-2", "title": "New conversation", "state": "active", "createdAt": "2026-08-22T00:00:00Z", "updatedAt": "2026-08-22T00:00:00Z", "archivedAt": null, "purgeAfter": null },
+      { "threadId": "thread-1", "title": "Previous", "state": "archived", "createdAt": "2026-08-21T00:00:00Z", "updatedAt": "2026-08-22T00:00:00Z", "archivedAt": "2026-08-22T00:00:00Z", "purgeAfter": "2026-08-25T00:00:00Z" }
+    ]
+  }
+}

package/fixtures/thread-load.request.json

@@ -0,0 +1,8 @@
+{
+  "target": "/chat/thread/load",
+  "direction": "request",
+  "body": {
+    "threadId": "thread-2",
+    "knownSnapshotVersion": 3
+  }
+}

package/fixtures/thread-load.response.json

@@ -0,0 +1,11 @@
+{
+  "target": "/chat/thread/load",
+  "direction": "response",
+  "body": {
+    "thread": { "threadId": "thread-2", "title": "New conversation", "state": "active", "createdAt": "2026-08-22T00:00:00Z", "updatedAt": "2026-08-22T00:00:00Z", "archivedAt": null, "purgeAfter": null },
+    "session": { "activityAtUnixMs": 0 },
+    "sync": { "mode": "snapshot", "snapshot": { "version": 0, "messages": [], "activeRun": null, "pendingInteraction": null, "runOutcomes": [] } },
+    "live": { "baseSnapshotVersion": 0, "lastOffset": 0, "events": [] },
+    "queue": { "queueVersion": 0, "items": [] }
+  }
+}

package/fixtures/thread-rotate.request.json

@@ -0,0 +1,12 @@
+{
+  "target": "/chat/thread/rotate",
+  "direction": "request",
+  "body": {
+    "operationId": "operation-1",
+    "threadId": "thread-1",
+    "expectedCatalogVersion": 2,
+    "expectedSnapshotVersion": 4,
+    "expectedSettingVersion": 1,
+    "reason": "idle_timeout"
+  }
+}

package/fixtures/thread-rotate.response.json

@@ -0,0 +1,12 @@
+{
+  "target": "/chat/thread/rotate",
+  "direction": "response",
+  "body": {
+    "catalogVersion": 4,
+    "activeThreadId": "thread-3",
+    "threads": [
+      { "threadId": "thread-3", "title": "New conversation", "state": "active", "createdAt": "2026-08-22T02:00:00Z", "updatedAt": "2026-08-22T02:00:00Z", "archivedAt": null, "purgeAfter": null },
+      { "threadId": "thread-2", "title": "Previous", "state": "archived", "createdAt": "2026-08-22T00:00:00Z", "updatedAt": "2026-08-22T02:00:00Z", "archivedAt": "2026-08-22T02:00:00Z", "archiveReason": "replaced", "purgeAfter": "2026-08-25T02:00:00Z" }
+    ]
+  }
+}

package/fixtures/turn-submit.request.json

@@ -0,0 +1,19 @@
+{
+  "target": "/chat/turn/submit",
+  "direction": "request",
+  "body": {
+    "requestId": "request-2",
+    "title": "Kitchen chat",
+    "content": {
+      "parts": [
+        { "type": "text", "text": "Turn on the lights" }
+      ]
+    },
+    "accessMode": "interactive",
+    "agentModelMode": "auto",
+    "temperature": null,
+    "allowTools": true,
+    "debug": false,
+    "occurredAtUnixMs": 1787587200000
+  }
+}

package/fixtures/turn-submit.response.json

@@ -0,0 +1,11 @@
+{
+  "target": "/chat/turn/submit",
+  "direction": "response",
+  "body": {
+    "requestId": "request-2",
+    "threadId": "thread-3",
+    "disposition": "queued",
+    "sessionDisposition": "rotated_idle_timeout",
+    "queueVersion": 1
+  }
+}

package/manifest/targets.v1.json

@@ -0,0 +1,22 @@
+{
+  "manifest": "mhome.conversation.targets.v1",
+  "contractVersion": "0.11.1",
+  "requestTargets": [
+    "/chat/thread/list",
+    "/chat/thread/create",
+    "/chat/thread/archive",
+    "/chat/thread/rotate",
+    "/chat/thread/load",
+    "/chat/message/enqueue",
+    "/chat/turn/submit",
+    "/chat/session/start",
+    "/chat/interaction/answer",
+    "/chat/queue/reorder",
+    "/chat/request/cancel",
+    "/chat/interaction/submit"
+  ],
+  "eventTargets": [
+    "/chat/event",
+    "/chat/debug"
+  ]
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@mhome/conversation-protocol",
+  "version": "0.11.1",
+  "description": "Build-time protocol artifacts for mhome.conversation",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mhome-ai/foundation.git",
+    "directory": "crates/conversation-api"
+  },
+  "homepage": "https://github.com/mhome-ai/foundation#readme",
+  "bugs": {
+    "url": "https://github.com/mhome-ai/foundation/issues"
+  },
+  "keywords": [
+    "mhome",
+    "protocol",
+    "json-schema",
+    "fixtures"
+  ],
+  "private": false,
+  "files": [
+    "protocol.json",
+    "manifest",
+    "contract",
+    "schema",
+    "fixtures",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./protocol.json": "./protocol.json",
+    "./manifest/*": "./manifest/*",
+    "./contract/*": "./contract/*",
+    "./schema/*": "./schema/*",
+    "./fixtures/*": "./fixtures/*"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/protocol.json

@@ -0,0 +1,11 @@
+{
+  "protocol": "mhome.conversation",
+  "contractVersion": "0.11.1",
+  "manifest": "manifest/targets.v1.json",
+  "schemas": {
+    "frame": "schema/conversation-frame.v2.schema.json"
+  },
+  "fixtures": {
+    "valid": "fixtures"
+  }
+}