mhome-conversation-api 4.4.0

Typed wire contract for the mHome conversation API
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

//! App Facade contract used by the canonical Agent implementation.

use async_trait::async_trait;
use serde::{Deserialize, Serialize};
use serde_json::Value;

use crate::execution::{ActionId, ExternalError, InvocationContext, OperationId};

/// Canonical App Facade request selected by Agent-owned tool code.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct FacadeRequest {
    /// Stable idempotency identifier for this tool operation.
    pub operation_id: OperationId,
    /// Canonical `/app/...` target. The Agent owns every tool-to-target mapping.
    pub target: String,
    /// Structured input validated and normalized by Agent-owned tool code.
    pub input: Value,
    /// Output projection, separate from the immutable business input.
    pub response_detail: crate::execution::ResponseDetail,
}

pub use crate::{InteractionCard, InteractionKind, InteractionTone};

/// Prepared operation awaiting an explicit commit or rejection.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PreparedAction {
    /// Stable action identifier used for idempotent commit and rejection.
    pub action_id: ActionId,
    /// Idempotency identifier supplied by Runtime.
    pub operation_id: OperationId,
    /// App Facade-generated preview suitable for user confirmation.
    pub card: InteractionCard,
    /// Opaque execution plan. Runtime persists it but never exposes it to the model or UI.
    #[serde(default)]
    pub payload: Value,
    /// App Facade revision that must still be current when committing.
    pub revision: u64,
}

/// Structured result returned by an App Facade operation.
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct FacadeResult {
    /// Canonical serialized `FacadeResponse`; never a bare business DTO.
    #[serde(deserialize_with = "deserialize_response")]
    pub value: Value,
    /// New prompt-context generation when this operation changed Agent-visible facts.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub context_invalidation: Option<crate::execution::ContextInvalidation>,
}

/// Environment-specific implementation of the App Facade boundary.
///
/// Implementations may execute in-process (`MeowCore`) or through RPC (agent-cloud/Lion), but they
/// cannot supply prompts, tools, workflows, or model-facing schemas.
#[async_trait]
pub trait AppFacade: Send + Sync {
    /// Executes a direct App Facade request.
    async fn invoke(
        &self,
        context: &InvocationContext,
        request: FacadeRequest,
    ) -> Result<FacadeResult, ExternalError>;

    /// Prepares a mutating operation without applying it.
    async fn prepare(
        &self,
        context: &InvocationContext,
        request: FacadeRequest,
    ) -> Result<PreparedAction, ExternalError>;

    /// Commits a prepared operation idempotently.
    async fn commit(
        &self,
        context: &InvocationContext,
        action: PreparedAction,
    ) -> Result<FacadeResult, ExternalError>;

    /// Rejects a prepared operation idempotently.
    async fn reject(
        &self,
        context: &InvocationContext,
        action: PreparedAction,
    ) -> Result<(), ExternalError>;
}

fn deserialize_response<'de, D: serde::Deserializer<'de>>(
    deserializer: D,
) -> Result<Value, D::Error> {
    use serde::de::Error;
    let response = crate::execution::FacadeResponse::deserialize(deserializer)?;
    serde_json::to_value(response).map_err(D::Error::custom)
}