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    /// `sha256:<64 lower hex>` content hash of this server binary's
91    /// experimental-surface bundle. Additive-optional: a host that predates the
92    /// member omits it, and the reader treats absence as unknown — never a
93    /// guessed value.
94    #[serde(skip_serializing_if = "Option::is_none")]
95    pub experimental_fingerprint: Option<String>,
96}
97
98/// The server runtime's platform family; may differ from the client's. Closed:
99/// the protocol fixes the value set, so widening it is a deliberate,
100/// gate-visible protocol change rather than a silent addition (a later
101/// `Closed`→`Open` flip is itself additive).
102#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
103#[serde(rename_all = "camelCase")]
104pub enum PlatformFamily {
105    /// Unix-family runtime (macOS, Linux).
106    Unix,
107    /// Windows runtime.
108    Windows,
109}
110
111/// The server's operating system. Closed, for the same reason as
112/// [`PlatformFamily`].
113#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
114#[serde(rename_all = "camelCase")]
115pub enum PlatformOs {
116    /// macOS.
117    Macos,
118    /// Linux.
119    Linux,
120    /// Windows.
121    Windows,
122}
123
124/// Whether this host writes its sessions to disk. A property of the host
125/// process, fixed at construction and identical for every session and every
126/// connection it serves — never requested, granted, or negotiated, which is why
127/// it is not a capability. Open: the unrepresented degraded state has candidate
128/// resolutions that add a third value here, so closed would make that a
129/// breaking change.
130#[derive(Debug, Clone, PartialEq, Eq)]
131#[non_exhaustive]
132pub enum SessionDurability {
133    /// Sessions are written to `session.jsonl` and can be resumed, read, and
134    /// forked across processes.
135    Durable,
136    /// Nothing reaches the filesystem; the session lives only in this host's
137    /// memory, and `session/resume`, `session/fork`, and `session/read` are
138    /// withheld with `methodNotFound`.
139    Ephemeral,
140    /// A value introduced by a newer host. Preserved so an older client can
141    /// conservatively assume no durability guarantee without failing the
142    /// handshake. Not a v1 server-emission value, so it is excluded from the
143    /// generated known-value schema while the enum remains declared open.
144    Unknown(String),
145}
146
147impl SessionDurability {
148    /// The exact wire spelling, including a future value an older client does
149    /// not understand.
150    #[must_use]
151    pub fn as_str(&self) -> &str {
152        match self {
153            Self::Durable => "durable",
154            Self::Ephemeral => "ephemeral",
155            Self::Unknown(value) => value,
156        }
157    }
158}
159
160impl Serialize for SessionDurability {
161    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
162    where
163        S: Serializer,
164    {
165        serializer.serialize_str(self.as_str())
166    }
167}
168
169impl<'de> Deserialize<'de> for SessionDurability {
170    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
171    where
172        D: Deserializer<'de>,
173    {
174        let value = String::deserialize(deserializer)?;
175        Ok(match value.as_str() {
176            "durable" => Self::Durable,
177            "ephemeral" => Self::Ephemeral,
178            _ => Self::Unknown(value),
179        })
180    }
181}
182
183/// Whether this host can enforce the sandbox. A property of the host process,
184/// probed once at construction and identical for every session and every
185/// connection it serves — never requested, granted, or negotiated, which is why
186/// it is not a capability. Open: a future enforcement posture arrives as a new
187/// value, read by older clients as unknown.
188#[derive(Debug, Clone, PartialEq, Eq)]
189#[non_exhaustive]
190pub enum SandboxAvailability {
191    /// Enforcement is possible on this host.
192    Available,
193    /// Enforcement is truly impossible (user-namespace denial, no usable
194    /// backend including embedded) — never mere missing-PATH bwrap. The
195    /// cause rides [`SandboxUnavailableReason`], when the host sends one.
196    Unavailable,
197    /// A value introduced by a newer host. Preserved so an older client can
198    /// fall back to its own probe without failing the handshake. Not a v1
199    /// server-emission value, so it is excluded from the generated
200    /// known-value schema while the enum remains declared open.
201    Unknown(String),
202}
203
204impl SandboxAvailability {
205    /// The exact wire spelling, including a future value an older client does
206    /// not understand.
207    #[must_use]
208    pub fn as_str(&self) -> &str {
209        match self {
210            Self::Available => "available",
211            Self::Unavailable => "unavailable",
212            Self::Unknown(value) => value,
213        }
214    }
215}
216
217impl Serialize for SandboxAvailability {
218    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
219    where
220        S: Serializer,
221    {
222        serializer.serialize_str(self.as_str())
223    }
224}
225
226impl<'de> Deserialize<'de> for SandboxAvailability {
227    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
228    where
229        D: Deserializer<'de>,
230    {
231        let value = String::deserialize(deserializer)?;
232        Ok(match value.as_str() {
233            "available" => Self::Available,
234            "unavailable" => Self::Unavailable,
235            _ => Self::Unknown(value),
236        })
237    }
238}
239
240/// Why sandbox enforcement is impossible on this host. Sent only when
241/// [`SandboxAvailability`] is `unavailable`; a client MUST NOT infer a
242/// reason when none is sent. Open: a future reason arrives as a new
243/// value, read by older clients as unknown.
244#[derive(Debug, Clone, PartialEq, Eq)]
245#[non_exhaustive]
246pub enum SandboxUnavailableReason {
247    /// Bubblewrap exists but cannot create user namespaces.
248    UserNamespacesDenied,
249    /// No capability-valid system bwrap on PATH and no usable embedded
250    /// fallback.
251    BubblewrapUnavailable,
252    /// A value introduced by a newer host, preserved for the same reason
253    /// as [`SandboxAvailability::Unknown`].
254    Unknown(String),
255}
256
257impl SandboxUnavailableReason {
258    /// The exact wire spelling, including a future value an older client does
259    /// not understand.
260    #[must_use]
261    pub fn as_str(&self) -> &str {
262        match self {
263            Self::UserNamespacesDenied => "userNamespacesDenied",
264            Self::BubblewrapUnavailable => "bubblewrapUnavailable",
265            Self::Unknown(value) => value,
266        }
267    }
268}
269
270impl Serialize for SandboxUnavailableReason {
271    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
272    where
273        S: Serializer,
274    {
275        serializer.serialize_str(self.as_str())
276    }
277}
278
279impl<'de> Deserialize<'de> for SandboxUnavailableReason {
280    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
281    where
282        D: Deserializer<'de>,
283    {
284        let value = String::deserialize(deserializer)?;
285        Ok(match value.as_str() {
286            "userNamespacesDenied" => Self::UserNamespacesDenied,
287            "bubblewrapUnavailable" => Self::BubblewrapUnavailable,
288            _ => Self::Unknown(value),
289        })
290    }
291}
292
293/// The `initialize` result.
294#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
295#[serde(rename_all = "camelCase")]
296#[non_exhaustive]
297pub struct InitializeResult {
298    /// Server identification.
299    pub server_info: ServerInfo,
300    /// Exact user-agent string presented to upstream model providers.
301    pub user_agent: String,
302    /// Absolute path of the muse home directory.
303    pub muse_home: String,
304    /// Server runtime platform family.
305    pub platform_family: PlatformFamily,
306    /// Server operating system.
307    pub platform_os: PlatformOs,
308    /// Envelope schema version and stable-surface fingerprint.
309    pub schema: SchemaInfo,
310    /// Subset of the requested capabilities, plus policy-implicit grants. Fixed
311    /// for the connection lifetime.
312    pub granted_capabilities: Vec<CapabilityName>,
313    /// Echo of the effective negotiated experimental setting.
314    pub experimental_api: bool,
315    /// Whether this host persists its sessions. Optional so adding it stays
316    /// backward compatible; a v1 host always sends it, and a client reads
317    /// absent as `durable` because no server that omits it has the ephemeral
318    /// profile.
319    #[serde(skip_serializing_if = "Option::is_none")]
320    pub session_durability: Option<SessionDurability>,
321    /// Whether this host can enforce the sandbox. Optional so adding it stays
322    /// backward compatible; a v1 host always sends it, and a client reads
323    /// absent as unknown — the host predates the field, so the client falls
324    /// back to its own probe rather than inventing an answer.
325    #[serde(skip_serializing_if = "Option::is_none")]
326    pub sandbox_availability: Option<SandboxAvailability>,
327    /// Why enforcement is impossible. Sent only when `sandbox_availability`
328    /// is `unavailable`; a client MUST NOT infer a reason when none is
329    /// sent.
330    #[serde(skip_serializing_if = "Option::is_none")]
331    pub sandbox_unavailable_reason: Option<SandboxUnavailableReason>,
332    /// The host's posture ceiling as a five-axis limits object: what a
333    /// connection may choose. **Experimental, same-user socket only**; absent
334    /// means the host has no limits regime, so there is nothing to narrow and
335    /// no read method to serve. Absent is never fabricated.
336    #[serde(skip_serializing_if = "Option::is_none")]
337    pub max_limits: Option<crate::msp::method::limits::SessionLimits>,
338    /// The launcher context this serve process started with. **Experimental**:
339    /// present exactly when `grantedCapabilities` lists `launchContext`, absent
340    /// otherwise.
341    #[serde(skip_serializing_if = "Option::is_none")]
342    pub launch_context: Option<LaunchContext>,
343}
344
345/// `InitializeResult.launchContext`: the two launcher variables of the serve
346/// process's environment, verbatim, read once at process start; one value for
347/// every connection and session the process hosts. Each member is `null` when
348/// its variable is unset.
349#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
350#[serde(rename_all = "camelCase")]
351#[non_exhaustive]
352pub struct LaunchContext {
353    /// `META_3PAI_INVOCATION_ID` (required, nullable).
354    pub invocation_id: Option<String>,
355    /// `META_3PAI_INVOCATION_CONTEXT` (required, nullable).
356    pub invocation_context: Option<String>,
357}