@mhome/conversation-protocol 1.1.1 → 1.3.0

package/README.md

@@ -19,3 +19,13 @@ Telegram forum topic without changing the provider account's base authorization
 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.
+
+## Execution contracts
+
+`execution` owns Agent command/event DTOs and deployment ports. `execution::wire` owns the cloud
+transport envelopes and `schema/execution` / `fixtures/execution` conformance assets. These moved
+from the retired Agent contract/protocol crates. Client-facing root modules remain unchanged.
+
+Model data is re-exported from `llm-api`; there is one model-message representation. User-facing
+messages intentionally use separate content types and never contain private model continuation.
+Runtime state machines, checkpoint formats, prompts and recovery policy remain in Agent Runtime.

package/fixtures/admission.event.json

@@ -0,0 +1,17 @@
+{
+  "target": "/chat/event",
+  "direction": "event",
+  "body": {
+    "type": "admission.changed",
+    "surfaceId": "cs1:cp:dXNlci0x",
+    "requestId": "request-3",
+    "admissionVersion": 8,
+    "occurredAt": "2026-08-22T03:00:00Z",
+    "data": {
+      "state": "bound",
+      "reason": "accepted",
+      "threadId": "thread-3",
+      "queueVersion": 1
+    }
+  }
+}

package/fixtures/execution/admission.v1.json

@@ -0,0 +1,37 @@
+{
+  "metadata": {
+    "version": 1,
+    "message_id": "message-5",
+    "correlation_id": "correlation-1",
+    "causation_id": "message-1",
+    "sent_at_unix_ms": 1700000000010,
+    "dispatch": {
+      "dispatch_id": "dispatch-1",
+      "agent_session_id": "agent-session-1"
+    }
+  },
+  "payload": {
+    "family": "command_response",
+    "payload": {
+      "type": "accepted",
+      "context": {
+        "scope": {
+          "tenant_id": "tenant-1",
+          "scope_id": "scope-1"
+        },
+        "actor": {
+          "user_id": "user-1",
+          "client_id": "client-1"
+        },
+        "thread_id": "thread-1",
+        "run_id": "run-1",
+        "operation_id": "operation-1",
+        "deadline_unix_ms": null,
+        "traceparent": null,
+        "surface_id": "cs1:cp:dXNlci0x"
+      },
+      "disposition": "queued",
+      "queue_revision": 1
+    }
+  }
+}

package/fixtures/execution/app-facade-prepare.v1.json

@@ -0,0 +1,43 @@
+{
+  "metadata": {
+    "version": 1,
+    "message_id": "message-3",
+    "correlation_id": "correlation-tool-1",
+    "causation_id": "message-1",
+    "sent_at_unix_ms": 1700000000500,
+    "dispatch": {
+      "dispatch_id": "dispatch-1",
+      "agent_session_id": "agent-session-1"
+    }
+  },
+  "payload": {
+    "family": "app_facade_request",
+    "payload": {
+      "phase": "prepare",
+      "context": {
+        "scope": {
+          "tenant_id": "tenant-1",
+          "scope_id": "scope-1"
+        },
+        "actor": {
+          "user_id": "user-1",
+          "client_id": "client-1"
+        },
+        "thread_id": "thread-1",
+        "run_id": "run-1",
+        "operation_id": "operation-1",
+        "deadline_unix_ms": null,
+        "traceparent": null,
+        "surface_id": "cs1:cp:dXNlci0x"
+      },
+      "request": {
+        "operation_id": "run-1:step:0:tool:call-1",
+        "target": "/app/capability/invoke",
+        "input": {
+          "capability": "device.turn_on",
+          "device_id": "device-1"
+        }
+      }
+    }
+  }
+}

package/fixtures/execution/app-facade-prepared.v1.json

@@ -0,0 +1,53 @@
+{
+  "metadata": {
+    "version": 1,
+    "message_id": "message-6",
+    "correlation_id": "correlation-tool-1",
+    "causation_id": "message-3",
+    "sent_at_unix_ms": 1700000000510,
+    "dispatch": {
+      "dispatch_id": "dispatch-1",
+      "agent_session_id": "agent-session-1"
+    }
+  },
+  "payload": {
+    "family": "app_facade_response",
+    "payload": {
+      "type": "prepared",
+      "action": {
+        "action_id": "action-1",
+        "operation_id": "run-1:step:0:tool:call-1",
+        "preview": {
+          "actionCode": "device.power.update",
+          "title": "Turn on device",
+          "message": "Turn on the kitchen light.",
+          "tone": "normal",
+          "details": [
+            {
+              "label": "Device",
+              "value": {
+                "type": "text",
+                "text": "Kitchen light"
+              }
+            },
+            {
+              "label": "Power",
+              "value": {
+                "type": "bool",
+                "value": true
+              }
+            }
+          ],
+          "proceedLabel": "Continue",
+          "rejectLabel": "Cancel"
+        },
+        "payload": {
+          "target": "/app/capability/invoke"
+        },
+        "revision": 7,
+        "approval": "when_interactive",
+        "interaction_kind": "approval"
+      }
+    }
+  }
+}

package/fixtures/execution/app-facade-user-action.v1.json

@@ -0,0 +1,54 @@
+{
+  "metadata": {
+    "version": 1,
+    "message_id": "message-user-action-1",
+    "correlation_id": "correlation-tool-2",
+    "causation_id": "message-prepare-2",
+    "sent_at_unix_ms": 1700000000520,
+    "dispatch": {
+      "dispatch_id": "dispatch-1",
+      "agent_session_id": "agent-session-1"
+    }
+  },
+  "payload": {
+    "family": "app_facade_response",
+    "payload": {
+      "type": "prepared",
+      "action": {
+        "action_id": "action-install-1",
+        "operation_id": "run-1:step:0:tool:call-2",
+        "preview": {
+          "actionCode": "integration.install",
+          "title": "Integration required",
+          "message": "Install Matter, then continue.",
+          "tone": "normal",
+          "details": [
+            {
+              "label": "Integrations",
+              "value": {
+                "type": "text_list",
+                "items": [
+                  "matter"
+                ]
+              }
+            }
+          ],
+          "proceedLabel": "I've installed it",
+          "rejectLabel": "Skip",
+          "clientTask": {
+            "type": "install_integrations",
+            "integrationIds": [
+              "matter"
+            ]
+          }
+        },
+        "payload": {
+          "target": "/app/integration/install"
+        },
+        "revision": 8,
+        "approval": "always",
+        "interaction_kind": "user_action"
+      }
+    }
+  }
+}

package/fixtures/execution/checkpoint-purge-ack.v1.json

@@ -0,0 +1,23 @@
+{
+  "metadata": {
+    "version": 1,
+    "message_id": "purge-ack-1",
+    "correlation_id": "purge-1",
+    "causation_id": "purge-1",
+    "sent_at_unix_ms": 1700000000001,
+    "dispatch": {
+      "dispatch_id": "dispatch-1",
+      "agent_session_id": "agent-session-1"
+    }
+  },
+  "payload": {
+    "family": "checkpoint_purge_ack",
+    "payload": {
+      "status": "deleted",
+      "purge_id": "purge-1",
+      "conversation_key": "conversation-1",
+      "thread_id": "thread-1",
+      "deleted_objects": 2
+    }
+  }
+}

package/fixtures/execution/checkpoint-purge.v1.json

@@ -0,0 +1,26 @@
+{
+  "metadata": {
+    "version": 1,
+    "message_id": "purge-1",
+    "correlation_id": "purge-1",
+    "causation_id": null,
+    "sent_at_unix_ms": 1700000000000,
+    "dispatch": {
+      "dispatch_id": "dispatch-1",
+      "agent_session_id": "agent-session-1"
+    }
+  },
+  "payload": {
+    "family": "checkpoint_purge",
+    "payload": {
+      "purge_id": "purge-1",
+      "conversation_key": "conversation-1",
+      "scope": {
+        "tenant_id": "tenant-1",
+        "scope_id": "scope-1"
+      },
+      "thread_id": "thread-1",
+      "surface_id": "cs1:cp:dXNlci0x"
+    }
+  }
+}

package/fixtures/execution/completed-event.v1.json

@@ -0,0 +1,62 @@
+{
+  "metadata": {
+    "version": 1,
+    "message_id": "message-2",
+    "correlation_id": "correlation-1",
+    "causation_id": "message-1",
+    "sent_at_unix_ms": 1700000001000,
+    "dispatch": {
+      "dispatch_id": "dispatch-1",
+      "agent_session_id": "agent-session-1"
+    }
+  },
+  "payload": {
+    "family": "event",
+    "payload": {
+      "event": {
+        "id": "event-1",
+        "sequence": 2,
+        "context": {
+          "scope": {
+            "tenant_id": "tenant-1",
+            "scope_id": "scope-1"
+          },
+          "actor": {
+            "user_id": "user-1",
+            "client_id": "client-1"
+          },
+          "thread_id": "thread-1",
+          "run_id": "run-1",
+          "operation_id": "operation-1",
+          "deadline_unix_ms": null,
+          "traceparent": null,
+          "surface_id": "cs1:cp:dXNlci0x"
+        },
+        "event": {
+          "type": "completed",
+          "result": {
+            "text": "done"
+          },
+          "usage": {
+            "model_requests": 1,
+            "reported_model_requests": 1,
+            "input_tokens": 10,
+            "output_tokens": 2,
+            "cached_input_tokens": null,
+            "reasoning_output_tokens": null,
+            "peak_input_tokens": 10,
+            "credits": null,
+            "tool_calls": 0,
+            "window_truncations": 0,
+            "trimmed_messages": 0
+          }
+        }
+      },
+      "checkpoint": {
+        "object_key": "checkpoints/abc.json",
+        "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "format_version": 1
+      }
+    }
+  }
+}

package/fixtures/execution/enqueue.v1.json

@@ -0,0 +1,213 @@
+{
+  "metadata": {
+    "version": 1,
+    "message_id": "message-1",
+    "correlation_id": "correlation-1",
+    "causation_id": null,
+    "sent_at_unix_ms": 1700000000000,
+    "dispatch": {
+      "dispatch_id": "dispatch-1",
+      "agent_session_id": "agent-session-1"
+    }
+  },
+  "payload": {
+    "family": "command",
+    "payload": {
+      "command": {
+        "type": "enqueue",
+        "context": {
+          "scope": {
+            "tenant_id": "tenant-1",
+            "scope_id": "scope-1"
+          },
+          "actor": {
+            "user_id": "user-1",
+            "client_id": "client-1"
+          },
+          "thread_id": "thread-1",
+          "run_id": "run-1",
+          "operation_id": "operation-1",
+          "deadline_unix_ms": null,
+          "traceparent": null,
+          "surface_id": "cs1:cp:dXNlci0x"
+        },
+        "message": {
+          "role": "user",
+          "content": [
+            {
+              "type": "text",
+              "text": "hello"
+            }
+          ]
+        },
+        "options": {
+          "use_case": "chat",
+          "model_mode": "auto",
+          "access_mode": "interactive",
+          "allow_tools": true,
+          "max_steps": 8,
+          "credit_budget": null,
+          "debug": false
+        }
+      },
+      "context_generation": {
+        "user_scope": "scope-1",
+        "identity": "identity-1",
+        "memory": "memory-1",
+        "integration_guide": "guide-1",
+        "installed_integrations": "installed-1",
+        "scope_integrations": "scope-integrations-1"
+      },
+      "llm_plan": {
+        "routes": [
+          {
+            "use_case": "chat",
+            "model_mode": "auto",
+            "revision": "1700000000000",
+            "route": {
+              "backend": "openrouter",
+              "profile": "cloud_openrouter",
+              "model": "openai/gpt-5.4-mini",
+              "provider_preferences": [
+                "OpenAI"
+              ],
+              "temperature": 0.5,
+              "max_output_tokens": 8192,
+              "context_window_tokens": 128000,
+              "cache_control": true,
+              "reasoning_effort": null
+            }
+          },
+          {
+            "use_case": "agent_info_merge",
+            "model_mode": "auto",
+            "revision": "1700000000000",
+            "route": {
+              "backend": "openrouter",
+              "profile": "cloud_openrouter",
+              "model": "openai/gpt-5.4-mini",
+              "provider_preferences": [
+                "OpenAI"
+              ],
+              "temperature": 0.5,
+              "max_output_tokens": 8192,
+              "context_window_tokens": 128000,
+              "cache_control": true,
+              "reasoning_effort": null
+            }
+          },
+          {
+            "use_case": "automation_judge",
+            "model_mode": "auto",
+            "revision": "1700000000000",
+            "route": {
+              "backend": "openrouter",
+              "profile": "cloud_openrouter",
+              "model": "openai/gpt-5.4-mini",
+              "provider_preferences": [
+                "OpenAI"
+              ],
+              "temperature": 0.5,
+              "max_output_tokens": 8192,
+              "context_window_tokens": 128000,
+              "cache_control": true,
+              "reasoning_effort": null
+            }
+          },
+          {
+            "use_case": "automation_diagnose",
+            "model_mode": "auto",
+            "revision": "1700000000000",
+            "route": {
+              "backend": "openrouter",
+              "profile": "cloud_openrouter",
+              "model": "openai/gpt-5.4-mini",
+              "provider_preferences": [
+                "OpenAI"
+              ],
+              "temperature": 0.5,
+              "max_output_tokens": 8192,
+              "context_window_tokens": 128000,
+              "cache_control": true,
+              "reasoning_effort": null
+            }
+          },
+          {
+            "use_case": "app_guide",
+            "model_mode": "auto",
+            "revision": "1700000000000",
+            "route": {
+              "backend": "openrouter",
+              "profile": "cloud_openrouter",
+              "model": "openai/gpt-5.4-mini",
+              "provider_preferences": [
+                "OpenAI"
+              ],
+              "temperature": 0.5,
+              "max_output_tokens": 8192,
+              "context_window_tokens": 128000,
+              "cache_control": true,
+              "reasoning_effort": null
+            }
+          },
+          {
+            "use_case": "workflow.action_operate",
+            "model_mode": "auto",
+            "revision": "1700000000000",
+            "route": {
+              "backend": "openrouter",
+              "profile": "cloud_openrouter",
+              "model": "openai/gpt-5.4-mini",
+              "provider_preferences": [
+                "OpenAI"
+              ],
+              "temperature": 0.5,
+              "max_output_tokens": 8192,
+              "context_window_tokens": 128000,
+              "cache_control": true,
+              "reasoning_effort": null
+            }
+          },
+          {
+            "use_case": "workflow.automation_generate",
+            "model_mode": "auto",
+            "revision": "1700000000000",
+            "route": {
+              "backend": "openrouter",
+              "profile": "cloud_openrouter",
+              "model": "openai/gpt-5.4-mini",
+              "provider_preferences": [
+                "OpenAI"
+              ],
+              "temperature": 0.5,
+              "max_output_tokens": 8192,
+              "context_window_tokens": 128000,
+              "cache_control": true,
+              "reasoning_effort": null
+            }
+          },
+          {
+            "use_case": "workflow.description_generate",
+            "model_mode": "auto",
+            "revision": "1700000000000",
+            "route": {
+              "backend": "openrouter",
+              "profile": "cloud_openrouter",
+              "model": "openai/gpt-5.4-mini",
+              "provider_preferences": [
+                "OpenAI"
+              ],
+              "temperature": 0.5,
+              "max_output_tokens": 8192,
+              "context_window_tokens": 128000,
+              "cache_control": true,
+              "reasoning_effort": null
+            }
+          }
+        ]
+      },
+      "base_checkpoint": null,
+      "abandoned_run_id": null
+    }
+  }
+}

package/fixtures/execution/event-ack.v1.json

@@ -0,0 +1,24 @@
+{
+  "metadata": {
+    "version": 1,
+    "message_id": "message-ack-1",
+    "correlation_id": "correlation-event-1",
+    "causation_id": "message-event-1",
+    "sent_at_unix_ms": 1700000000000,
+    "dispatch": {
+      "dispatch_id": "dispatch-1",
+      "agent_session_id": "agent-session-1"
+    }
+  },
+  "payload": {
+    "family": "event_ack",
+    "payload": {
+      "event_id": "event-1",
+      "checkpoint": {
+        "object_key": "checkpoints/abc.json",
+        "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "format_version": 1
+      }
+    }
+  }
+}

package/fixtures/execution/failed-event.v1.json

@@ -0,0 +1,61 @@
+{
+  "metadata": {
+    "version": 1,
+    "message_id": "message-3",
+    "correlation_id": "correlation-1",
+    "causation_id": "message-2",
+    "sent_at_unix_ms": 1700000002000,
+    "dispatch": {
+      "dispatch_id": "dispatch-1",
+      "agent_session_id": "agent-session-1"
+    }
+  },
+  "payload": {
+    "family": "event",
+    "payload": {
+      "event": {
+        "id": "event-2",
+        "sequence": 3,
+        "context": {
+          "scope": {
+            "tenant_id": "tenant-1",
+            "scope_id": "scope-1"
+          },
+          "actor": {
+            "user_id": "user-1",
+            "client_id": "client-1"
+          },
+          "thread_id": "thread-1",
+          "run_id": "run-1",
+          "operation_id": "operation-1",
+          "deadline_unix_ms": null,
+          "traceparent": null,
+          "surface_id": "cs1:cp:dXNlci0x"
+        },
+        "event": {
+          "type": "failed",
+          "code": "OUTPUT_TRUNCATED",
+          "message": "Model output reached its configured length limit",
+          "usage": {
+            "model_requests": 1,
+            "reported_model_requests": 1,
+            "input_tokens": 10,
+            "output_tokens": 20,
+            "cached_input_tokens": null,
+            "reasoning_output_tokens": null,
+            "peak_input_tokens": 10,
+            "credits": 7,
+            "tool_calls": 0,
+            "window_truncations": 0,
+            "trimmed_messages": 0
+          }
+        }
+      },
+      "checkpoint": {
+        "object_key": "checkpoints/abc.json",
+        "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        "format_version": 1
+      }
+    }
+  }
+}