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;
4pub use launch_context::LaunchContext;
5pub use sandbox::SandboxAvailability;
6pub use sandbox::SandboxUnavailableReason;
7use serde::Deserialize;
8use serde::Deserializer;
9use serde::Serialize;
10use serde::Serializer;
11
12pub(crate) mod launch_context;
13pub(crate) mod sandbox;
14
15/// Client identification inside `initialize` params. Diagnostics and telemetry
16/// attribution only; never an authority claim.
17#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
18#[serde(rename_all = "camelCase")]
19pub struct ClientInfo {
20 /// Machine identifier, `[a-z0-9_]+`.
21 pub name: String,
22 /// Client version string.
23 pub version: String,
24 /// Human display name.
25 #[serde(skip_serializing_if = "Option::is_none")]
26 pub title: Option<String>,
27}
28
29/// The client's requested capability posture. Every member defaults; an absent
30/// `capabilities` object means all defaults.
31#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
32#[serde(rename_all = "camelCase")]
33pub struct ClientCapabilities {
34 /// Opt into experimental methods, fields, and variants (default `false`).
35 #[serde(skip_serializing_if = "Option::is_none")]
36 pub experimental_api: Option<bool>,
37 /// Exact notification method names the client declines; no wildcards;
38 /// unknown names accepted and ignored; the protected set cannot be opted
39 /// out.
40 #[serde(skip_serializing_if = "Option::is_none")]
41 pub opt_out_notification_methods: Option<Vec<String>>,
42 /// Names from the capability registry. Unknown entries are not an error
43 /// and simply do not appear in `grantedCapabilities` — which is why this
44 /// is a list of free strings rather than of registry names.
45 #[serde(skip_serializing_if = "Option::is_none")]
46 pub requested_capabilities: Option<Vec<String>>,
47 /// Whether this client can render a `userInput/request` dialog and answer
48 /// it. **Absent means capable**: a client that predates the member keeps
49 /// today's contract, so no existing client changes its handshake. `false`
50 /// makes the host withhold `userInput/request` toward this client — the
51 /// additive-optional-field + withheld-method convention.
52 ///
53 /// Deliberately NOT a `requestedCapabilities` name: that registry records
54 /// operations a host GRANTS, and whether a client can draw a dialog is a
55 /// fact about the client, never a privilege the host hands out.
56 #[serde(skip_serializing_if = "Option::is_none")]
57 pub user_input_dialogs: Option<bool>,
58 /// The client offers a skill catalog for the sessions it drives.
59 /// **Experimental**: honoured only with `experimentalApi` and the host's
60 /// `skill_provider` gate open; the result echoes the effective value.
61 #[serde(skip_serializing_if = "Option::is_none")]
62 pub skill_provider: Option<crate::msp::method::skill_provider::SkillProviderCapability>,
63}
64
65/// `initialize` request params.
66#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
67#[serde(rename_all = "camelCase")]
68pub struct InitializeParams {
69 /// Client identification.
70 pub client_info: ClientInfo,
71 /// Capability posture; absent means all defaults.
72 #[serde(skip_serializing_if = "Option::is_none")]
73 pub capabilities: Option<ClientCapabilities>,
74}
75
76/// Server identification inside [`InitializeResult`].
77#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
78#[serde(rename_all = "camelCase")]
79#[non_exhaustive]
80pub struct ServerInfo {
81 /// Server name.
82 pub name: String,
83 /// Server version string.
84 pub version: String,
85}
86
87/// The `schema` pair in [`InitializeResult`]. `version` is the wire
88/// **envelope** schema version — distinct from the session-view
89/// `schemaVersion`, the raw-log `schema_version`, and the 0.x/1.0 stability
90/// posture, which is not on the wire at all.
91#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
92#[serde(rename_all = "camelCase")]
93#[non_exhaustive]
94pub struct SchemaInfo {
95 /// Envelope schema version; `1` in v1, expected to stay `1` for a long
96 /// time.
97 pub version: u32,
98 /// `sha256:<64 lower hex>` content hash of this server binary's
99 /// stable-surface bundle. A mismatch is a warning condition, not an error.
100 pub fingerprint: String,
101 /// `sha256:<64 lower hex>` content hash of this server binary's
102 /// experimental-surface bundle. Additive-optional: a host that predates the
103 /// member omits it, and the reader treats absence as unknown — never a
104 /// guessed value.
105 #[serde(skip_serializing_if = "Option::is_none")]
106 pub experimental_fingerprint: Option<String>,
107 /// The host's declared compatibility epoch: the count of declared
108 /// non-additive advances of the stable surface. A client reads a
109 /// `fingerprint` mismatch by comparing this with its own pin: equal, every
110 /// difference is additive; different, a declared non-additive advance lies
111 /// between. Additive-optional: a host that predates the member omits it,
112 /// and the reader treats absence as unknown, never a guessed value.
113 #[serde(skip_serializing_if = "Option::is_none")]
114 pub compatibility_epoch: Option<u32>,
115}
116
117/// The server runtime's platform family; may differ from the client's. Closed:
118/// the protocol fixes the value set, so widening it is a deliberate,
119/// gate-visible protocol change rather than a silent addition (a later
120/// `Closed`→`Open` flip is itself additive).
121#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
122#[serde(rename_all = "camelCase")]
123pub enum PlatformFamily {
124 /// Unix-family runtime (macOS, Linux).
125 Unix,
126 /// Windows runtime.
127 Windows,
128}
129
130/// The server's operating system. Closed, for the same reason as
131/// [`PlatformFamily`].
132#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
133#[serde(rename_all = "camelCase")]
134pub enum PlatformOs {
135 /// macOS.
136 Macos,
137 /// Linux.
138 Linux,
139 /// Windows.
140 Windows,
141}
142
143/// Whether this host writes its sessions to disk. A property of the host
144/// process, fixed at construction and identical for every session and every
145/// connection it serves — never requested, granted, or negotiated, which is why
146/// it is not a capability. Open: the unrepresented degraded state has candidate
147/// resolutions that add a third value here, so closed would make that a
148/// breaking change.
149#[derive(Debug, Clone, PartialEq, Eq)]
150#[non_exhaustive]
151pub enum SessionDurability {
152 /// Sessions are written to `session.jsonl` and can be resumed, read, and
153 /// forked across processes.
154 Durable,
155 /// Nothing reaches the filesystem; the session lives only in this host's
156 /// memory, and `session/resume`, `session/fork`, and `session/read` are
157 /// withheld with `methodNotFound`.
158 Ephemeral,
159 /// A value introduced by a newer host. Preserved so an older client can
160 /// conservatively assume no durability guarantee without failing the
161 /// handshake. Not a v1 server-emission value, so it is excluded from the
162 /// generated known-value schema while the enum remains declared open.
163 Unknown(String),
164}
165
166impl SessionDurability {
167 /// The exact wire spelling, including a future value an older client does
168 /// not understand.
169 #[must_use]
170 pub fn as_str(&self) -> &str {
171 match self {
172 Self::Durable => "durable",
173 Self::Ephemeral => "ephemeral",
174 Self::Unknown(value) => value,
175 }
176 }
177}
178
179impl Serialize for SessionDurability {
180 fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
181 where
182 S: Serializer,
183 {
184 serializer.serialize_str(self.as_str())
185 }
186}
187
188impl<'de> Deserialize<'de> for SessionDurability {
189 fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
190 where
191 D: Deserializer<'de>,
192 {
193 let value = String::deserialize(deserializer)?;
194 Ok(match value.as_str() {
195 "durable" => Self::Durable,
196 "ephemeral" => Self::Ephemeral,
197 _ => Self::Unknown(value),
198 })
199 }
200}
201
202/// The `initialize` result.
203#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
204#[serde(rename_all = "camelCase")]
205#[non_exhaustive]
206pub struct InitializeResult {
207 /// Server identification.
208 pub server_info: ServerInfo,
209 /// Exact user-agent string presented to upstream model providers.
210 pub user_agent: String,
211 /// Absolute path of the muse home directory.
212 pub muse_home: String,
213 /// Server runtime platform family.
214 pub platform_family: PlatformFamily,
215 /// Server operating system.
216 pub platform_os: PlatformOs,
217 /// Envelope schema version and stable-surface fingerprint.
218 pub schema: SchemaInfo,
219 /// Subset of the requested capabilities, plus policy-implicit grants. Fixed
220 /// for the connection lifetime.
221 pub granted_capabilities: Vec<CapabilityName>,
222 /// Echo of the effective negotiated experimental setting.
223 pub experimental_api: bool,
224 /// Whether this host persists its sessions. Optional so adding it stays
225 /// backward compatible; a v1 host always sends it, and a client reads
226 /// absent as `durable` because no server that omits it has the ephemeral
227 /// profile.
228 #[serde(skip_serializing_if = "Option::is_none")]
229 pub session_durability: Option<SessionDurability>,
230 /// Whether this host can enforce the sandbox. Optional so adding it stays
231 /// backward compatible; a v1 host always sends it, and a client reads
232 /// absent as unknown — the host predates the field, so the client falls
233 /// back to its own probe rather than inventing an answer.
234 #[serde(skip_serializing_if = "Option::is_none")]
235 pub sandbox_availability: Option<SandboxAvailability>,
236 /// Why enforcement is impossible. Sent only when `sandbox_availability`
237 /// is `unavailable`; a client MUST NOT infer a reason when none is
238 /// sent.
239 #[serde(skip_serializing_if = "Option::is_none")]
240 pub sandbox_unavailable_reason: Option<SandboxUnavailableReason>,
241 /// The host's posture ceiling as a five-axis limits object: what a
242 /// connection may choose. **Experimental, same-user socket only**; absent
243 /// means the host has no limits regime, so there is nothing to narrow and
244 /// no read method to serve. Absent is never fabricated.
245 #[serde(skip_serializing_if = "Option::is_none")]
246 pub max_limits: Option<crate::msp::method::limits::SessionLimits>,
247 /// The launcher context this serve process started with. **Experimental**:
248 /// present exactly when `grantedCapabilities` lists `launchContext`, absent
249 /// otherwise.
250 #[serde(skip_serializing_if = "Option::is_none")]
251 pub launch_context: Option<LaunchContext>,
252 /// The effective Skill Provider capability. **Experimental**: present
253 /// exactly when the host's `skill_provider` gate is open, the connection
254 /// negotiated `experimentalApi`, and the client declared version 1; absent
255 /// otherwise.
256 #[serde(skip_serializing_if = "Option::is_none")]
257 pub skill_provider: Option<crate::msp::method::skill_provider::SkillProviderCapability>,
258}