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