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.

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.

Cloud admission model snapshot

Every cloud LlmRoute carries a required model_snapshot containing confirmed capabilities and catalog generation_support (the camelCase metadata.generationSupport shape). Lion persists it with desired parameters at request admission. Deployments adapt preferences against these immutable facts; tool rounds and approval resumption never rediscover current metadata. The portable CompletionRequest and its caller-owned constraints are unchanged. An old plan without the snapshot fails decoding instead of silently changing behavior. This development contract change must be published and adopted by Lion and Cloud together before deployment.