Skip to main content

muse_code_sdk/msp/
handshake.rs

1// @generated from the MSP stable schema and protocol sources; do not edit by hand.
2
3use crate::msp::capability::CapabilityName;
4use serde::Deserialize;
5use serde::Deserializer;
6use serde::Serialize;
7use serde::Serializer;
8
9/// Client identification inside `initialize` params. Diagnostics and telemetry
10/// attribution only; never an authority claim.
11#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
12#[serde(rename_all = "camelCase")]
13pub struct ClientInfo {
14    /// Machine identifier, `[a-z0-9_]+`.
15    pub name: String,
16    /// Client version string.
17    pub version: String,
18    /// Human display name.
19    #[serde(skip_serializing_if = "Option::is_none")]
20    pub title: Option<String>,
21}
22
23/// The client's requested capability posture. Every member defaults; an absent
24/// `capabilities` object means all defaults.
25#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
26#[serde(rename_all = "camelCase")]
27pub struct ClientCapabilities {
28    /// Opt into experimental methods, fields, and variants (default `false`).
29    #[serde(skip_serializing_if = "Option::is_none")]
30    pub experimental_api: Option<bool>,
31    /// Exact notification method names the client declines; no wildcards;
32    /// unknown names accepted and ignored; the protected set cannot be opted
33    /// out.
34    #[serde(skip_serializing_if = "Option::is_none")]
35    pub opt_out_notification_methods: Option<Vec<String>>,
36    /// Names from the capability registry. Unknown entries are not an error
37    /// and simply do not appear in `grantedCapabilities` — which is why this
38    /// is a list of free strings rather than of registry names.
39    #[serde(skip_serializing_if = "Option::is_none")]
40    pub requested_capabilities: Option<Vec<String>>,
41    /// Whether this client can render a `userInput/request` dialog and answer
42    /// it. **Absent means capable**: a client that predates the member keeps
43    /// today's contract, so no existing client changes its handshake. `false`
44    /// makes the host withhold `userInput/request` toward this client — the
45    /// additive-optional-field + withheld-method convention.
46    ///
47    /// Deliberately NOT a `requestedCapabilities` name: that registry records
48    /// operations a host GRANTS, and whether a client can draw a dialog is a
49    /// fact about the client, never a privilege the host hands out.
50    #[serde(skip_serializing_if = "Option::is_none")]
51    pub user_input_dialogs: Option<bool>,
52}
53
54/// `initialize` request params.
55#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
56#[serde(rename_all = "camelCase")]
57pub struct InitializeParams {
58    /// Client identification.
59    pub client_info: ClientInfo,
60    /// Capability posture; absent means all defaults.
61    #[serde(skip_serializing_if = "Option::is_none")]
62    pub capabilities: Option<ClientCapabilities>,
63}
64
65/// Server identification inside [`InitializeResult`].
66#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
67#[serde(rename_all = "camelCase")]
68#[non_exhaustive]
69pub struct ServerInfo {
70    /// Server name.
71    pub name: String,
72    /// Server version string.
73    pub version: String,
74}
75
76/// The `schema` pair in [`InitializeResult`]. `version` is the wire
77/// **envelope** schema version — distinct from the session-view
78/// `schemaVersion`, the raw-log `schema_version`, and the 0.x/1.0 stability
79/// posture, which is not on the wire at all.
80#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
81#[serde(rename_all = "camelCase")]
82#[non_exhaustive]
83pub struct SchemaInfo {
84    /// Envelope schema version; `1` in v1, expected to stay `1` for a long
85    /// time.
86    pub version: u32,
87    /// `sha256:<64 lower hex>` content hash of this server binary's
88    /// stable-surface bundle. A mismatch is a warning condition, not an error.
89    pub fingerprint: String,
90}
91
92/// The server runtime's platform family; may differ from the client's. Closed:
93/// the protocol spec fixes the value set, so widening it is a deliberate,
94/// gate-visible protocol change rather than a silent addition.
95#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
96#[serde(rename_all = "camelCase")]
97pub enum PlatformFamily {
98    /// Unix-family runtime (macOS, Linux).
99    Unix,
100    /// Windows runtime.
101    Windows,
102}
103
104/// The server's operating system. Closed, for the same reason as
105/// [`PlatformFamily`].
106#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
107#[serde(rename_all = "camelCase")]
108pub enum PlatformOs {
109    /// macOS.
110    Macos,
111    /// Linux.
112    Linux,
113    /// Windows.
114    Windows,
115}
116
117/// Whether this host writes its sessions to disk. A property of the host
118/// process, fixed at construction and identical for every session and every
119/// connection it serves — never requested, granted, or negotiated, which is why
120/// it is not a capability. Open: the unrepresented degraded state has candidate
121/// resolutions that add a third value here, so closed would make that a
122/// breaking change.
123#[derive(Debug, Clone, PartialEq, Eq)]
124#[non_exhaustive]
125pub enum SessionDurability {
126    /// Sessions are written to `session.jsonl` and can be resumed, read, and
127    /// forked across processes.
128    Durable,
129    /// Nothing reaches the filesystem; the session lives only in this host's
130    /// memory, and `session/resume`, `session/fork`, and `session/read` are
131    /// withheld with `methodNotFound`.
132    Ephemeral,
133    /// A value introduced by a newer host. Preserved so an older client can
134    /// conservatively assume no durability guarantee without failing the
135    /// handshake. Not a v1 server-emission value, so it is excluded from the
136    /// generated known-value schema while the enum remains declared open.
137    Unknown(String),
138}
139
140impl SessionDurability {
141    /// The exact wire spelling, including a future value an older client does
142    /// not understand.
143    #[must_use]
144    pub fn as_str(&self) -> &str {
145        match self {
146            Self::Durable => "durable",
147            Self::Ephemeral => "ephemeral",
148            Self::Unknown(value) => value,
149        }
150    }
151}
152
153impl Serialize for SessionDurability {
154    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
155    where
156        S: Serializer,
157    {
158        serializer.serialize_str(self.as_str())
159    }
160}
161
162impl<'de> Deserialize<'de> for SessionDurability {
163    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
164    where
165        D: Deserializer<'de>,
166    {
167        let value = String::deserialize(deserializer)?;
168        Ok(match value.as_str() {
169            "durable" => Self::Durable,
170            "ephemeral" => Self::Ephemeral,
171            _ => Self::Unknown(value),
172        })
173    }
174}
175
176/// Whether this host can enforce the sandbox. A property of the host process,
177/// probed once at construction and identical for every session and every
178/// connection it serves — never requested, granted, or negotiated, which is why
179/// it is not a capability. Open: a future enforcement posture arrives as a new
180/// value, read by older clients as unknown.
181#[derive(Debug, Clone, PartialEq, Eq)]
182#[non_exhaustive]
183pub enum SandboxAvailability {
184    /// Enforcement is possible on this host.
185    Available,
186    /// Enforcement is truly impossible (user-namespace denial, no usable
187    /// backend including embedded) — never mere missing-PATH bwrap. The
188    /// cause rides [`SandboxUnavailableReason`], when the host sends one.
189    Unavailable,
190    /// A value introduced by a newer host. Preserved so an older client can
191    /// fall back to its own probe without failing the handshake. Not a v1
192    /// server-emission value, so it is excluded from the generated
193    /// known-value schema while the enum remains declared open.
194    Unknown(String),
195}
196
197impl SandboxAvailability {
198    /// The exact wire spelling, including a future value an older client does
199    /// not understand.
200    #[must_use]
201    pub fn as_str(&self) -> &str {
202        match self {
203            Self::Available => "available",
204            Self::Unavailable => "unavailable",
205            Self::Unknown(value) => value,
206        }
207    }
208}
209
210impl Serialize for SandboxAvailability {
211    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
212    where
213        S: Serializer,
214    {
215        serializer.serialize_str(self.as_str())
216    }
217}
218
219impl<'de> Deserialize<'de> for SandboxAvailability {
220    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
221    where
222        D: Deserializer<'de>,
223    {
224        let value = String::deserialize(deserializer)?;
225        Ok(match value.as_str() {
226            "available" => Self::Available,
227            "unavailable" => Self::Unavailable,
228            _ => Self::Unknown(value),
229        })
230    }
231}
232
233/// Why sandbox enforcement is impossible on this host. Sent only when
234/// [`SandboxAvailability`] is `unavailable`; a client MUST NOT infer a
235/// reason when none is sent. Open: a future reason arrives as a new
236/// value, read by older clients as unknown.
237#[derive(Debug, Clone, PartialEq, Eq)]
238#[non_exhaustive]
239pub enum SandboxUnavailableReason {
240    /// Bubblewrap exists but cannot create user namespaces.
241    UserNamespacesDenied,
242    /// No capability-valid system bwrap on PATH and no usable embedded
243    /// fallback.
244    BubblewrapUnavailable,
245    /// A value introduced by a newer host, preserved for the same reason
246    /// as [`SandboxAvailability::Unknown`].
247    Unknown(String),
248}
249
250impl SandboxUnavailableReason {
251    /// The exact wire spelling, including a future value an older client does
252    /// not understand.
253    #[must_use]
254    pub fn as_str(&self) -> &str {
255        match self {
256            Self::UserNamespacesDenied => "userNamespacesDenied",
257            Self::BubblewrapUnavailable => "bubblewrapUnavailable",
258            Self::Unknown(value) => value,
259        }
260    }
261}
262
263impl Serialize for SandboxUnavailableReason {
264    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
265    where
266        S: Serializer,
267    {
268        serializer.serialize_str(self.as_str())
269    }
270}
271
272impl<'de> Deserialize<'de> for SandboxUnavailableReason {
273    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
274    where
275        D: Deserializer<'de>,
276    {
277        let value = String::deserialize(deserializer)?;
278        Ok(match value.as_str() {
279            "userNamespacesDenied" => Self::UserNamespacesDenied,
280            "bubblewrapUnavailable" => Self::BubblewrapUnavailable,
281            _ => Self::Unknown(value),
282        })
283    }
284}
285
286/// The `initialize` result.
287#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
288#[serde(rename_all = "camelCase")]
289#[non_exhaustive]
290pub struct InitializeResult {
291    /// Server identification.
292    pub server_info: ServerInfo,
293    /// Exact user-agent string presented to upstream model providers.
294    pub user_agent: String,
295    /// Absolute path of the muse home directory.
296    pub muse_home: String,
297    /// Server runtime platform family.
298    pub platform_family: PlatformFamily,
299    /// Server operating system.
300    pub platform_os: PlatformOs,
301    /// Envelope schema version and stable-surface fingerprint.
302    pub schema: SchemaInfo,
303    /// Subset of the requested capabilities, plus policy-implicit grants. Fixed
304    /// for the connection lifetime.
305    pub granted_capabilities: Vec<CapabilityName>,
306    /// Echo of the effective negotiated experimental setting.
307    pub experimental_api: bool,
308    /// Whether this host persists its sessions. Optional so the addition is
309    /// additive under the protocol spec; a v1 host always sends it, and a
310    /// client reads absent as `durable` because no server that omits it has the
311    /// ephemeral profile.
312    #[serde(skip_serializing_if = "Option::is_none")]
313    pub session_durability: Option<SessionDurability>,
314    /// Whether this host can enforce the sandbox. Optional so the addition is
315    /// additive under the protocol spec; a v1 host always sends it, and a
316    /// client reads absent as unknown — the host predates the field, so the
317    /// client falls back to its own probe rather than inventing an answer.
318    #[serde(skip_serializing_if = "Option::is_none")]
319    pub sandbox_availability: Option<SandboxAvailability>,
320    /// Why enforcement is impossible. Sent only when `sandbox_availability`
321    /// is `unavailable`; a client MUST NOT infer a reason when none is
322    /// sent.
323    #[serde(skip_serializing_if = "Option::is_none")]
324    pub sandbox_unavailable_reason: Option<SandboxUnavailableReason>,
325}