muse_code_sdk/msp/method/turn.rs
1// @generated from the MSP stable schema and protocol sources; do not edit by hand.
2
3use serde::Deserialize;
4use serde::Serialize;
5
6/// The ack `status`: `accepted` for every admitted command. `session/compact`
7/// is the one method that may additionally answer `noop`
8/// ([`crate::msp::method::runtime::CompactStatus`]); no other command uses
9/// another status.
10#[derive(Debug, Clone, PartialEq, Eq)]
11#[non_exhaustive]
12pub enum CommandStatus {
13 /// The command was admitted.
14 Accepted,
15 /// A value from a newer host, kept verbatim so an older client decodes the
16 /// rest of the message. Excluded from the generated schema while the enum
17 /// stays declared open; never construct it with a known word.
18 Unknown(String),
19}
20
21/// One ordered content part of a turn submission. File mentions are text, not a
22/// part type: write `@relative/path` in a text part. A structured `mention`
23/// part is reserved and currently rejected, and an unknown part type is
24/// `invalidParams` — which is what closes [`TurnInputPartType`].
25///
26/// Modelled as a discriminated flat object rather than a Rust `enum`, the
27/// convention [`crate::msp::view::approval::ApprovalSubject`] already
28/// established for a wire union in this crate: the v1 schema model names no
29/// object-variant union shape and fails closed on one. The serialized JSON is
30/// the protocol spec shape either way; what a flat object cannot express is
31/// "`mediaType` is required exactly when `type` is `image`".
32///
33/// **RULED: the precedent is accepted.** A strict union node kind may be funded
34/// later as a follow-up; if it is, it must cover
35/// [`crate::msp::method::lifecycle::PendingRequestPointer`] too.
36#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
37#[serde(rename_all = "camelCase")]
38pub struct TurnInputPart {
39 /// The part type.
40 #[serde(rename = "type")]
41 pub part_type: TurnInputPartType,
42 /// User prompt text, on a `text` part. Multiple text parts are joined in
43 /// order into the turn's prompt.
44 #[serde(skip_serializing_if = "Option::is_none")]
45 pub text: Option<String>,
46 /// Media type, required on an `image` part.
47 #[serde(skip_serializing_if = "Option::is_none")]
48 pub media_type: Option<String>,
49 /// Base64 payload, required on an `image` part. Invalid base64 or an
50 /// empty payload is rejected with invalid params.
51 #[serde(skip_serializing_if = "Option::is_none")]
52 pub base64_data: Option<String>,
53 /// Pixel width; must be provided together with `height` or not at all.
54 /// Published as a `dependentRequired` pair under a tracked change.
55 #[serde(skip_serializing_if = "Option::is_none")]
56 pub width: Option<u64>,
57 /// Pixel height; must be provided together with `width` or not at all.
58 #[serde(skip_serializing_if = "Option::is_none")]
59 pub height: Option<u64>,
60 /// The skill to invoke, required on a `skill` part: a bare or
61 /// plugin-qualified shortcut token from `skill/list`. The HOST resolves and
62 /// expands; an unknown selector is the typed `-32032 skillNotFound` request
63 /// error.
64 #[serde(skip_serializing_if = "Option::is_none")]
65 pub selector: Option<String>,
66 /// Free-text skill arguments, optional on a `skill` part — the wire twin of
67 /// what the TUI accepts after the shortcut token.
68 #[serde(skip_serializing_if = "Option::is_none")]
69 pub arguments: Option<String>,
70 /// The picked copy's source, optional on a `skill` part: the catalog-row
71 /// `source` values. When present the host resolves the exact `(selector,
72 /// source)` row; when absent the governing rules bare resolution applies
73 /// byte-for-byte. Closed: an unknown value is `invalidParams`, never a
74 /// fall-through.
75 #[serde(skip_serializing_if = "Option::is_none")]
76 pub source: Option<crate::msp::method::skill::SkillInvocationSource>,
77 /// The upload receipt, required on a `video` part: the client-minted id
78 /// `media/upload` echoed.
79 #[serde(skip_serializing_if = "Option::is_none")]
80 pub upload_id: Option<String>,
81}
82
83/// The `type` discriminator of a turn input part. Closed: an unknown part type
84/// is `invalidParams`.
85#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
86#[serde(rename_all = "camelCase")]
87pub enum TurnInputPartType {
88 /// A user prompt text part.
89 Text,
90 /// An inline image part, the runtime's native image intake shape. Inline
91 /// base64 lives inside the frame cap, so an oversized submit fails
92 /// `inputTooLarge` and must be shrunk client-side.
93 Image,
94 /// An explicit skill invocation the host expands. `turn/start` only; at
95 /// most one per submission, combinable only with `image` parts.
96 Skill,
97 /// A video attachment by reference. The part carries the `uploadId` receipt
98 /// only; the host joins metadata from the stored upload. An unknown or
99 /// expired id fails the whole request `-32038 uploadNotFound`.
100 Video,
101}
102
103/// The reasoning-effort tier sampled at submission. The **same closed tier
104/// vocabulary** on both the fresh-turn and steer lanes, spelled identically;
105/// invalid tiers are invalid params. `none` is a tier of the vocabulary (ask
106/// for no reasoning), not a way to say "unset".
107#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
108#[serde(rename_all = "camelCase")]
109pub enum ReasoningEffort {
110 /// Ask for no reasoning.
111 None,
112 /// Minimal reasoning.
113 Minimal,
114 /// Low reasoning.
115 Low,
116 /// Medium reasoning.
117 Medium,
118 /// High reasoning.
119 High,
120 /// Extra-high reasoning.
121 Xhigh,
122 /// Max reasoning.
123 Max,
124 /// Ultra reasoning.
125 Ultra,
126}
127
128/// Disposition when a turn is already running. The wire default is `queue`: an
129/// SDK caller who has not looked at session state should not silently mutate an
130/// in-flight turn.
131#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
132#[serde(rename_all = "camelCase")]
133pub enum IfBusy {
134 /// Deliver the input as the next turn after the current one finishes.
135 Queue,
136 /// Inject the input into the running turn.
137 Steer,
138 /// Interrupt the running turn and start a fresh turn with this input.
139 Replace,
140}
141
142/// The queued `!` shell action a `turn/start` carries: the `!cmd` typed while a
143/// turn runs. The shell's command id derives from the carrying turn's
144/// `commandId`, exactly as the app's own queued submit does; the params'
145/// sibling `displayText` carries the `!…` presentation form.
146#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
147#[serde(rename_all = "camelCase")]
148pub struct TurnUserShell {
149 /// The shell command text, without the leading `!`.
150 pub command_text: String,
151}
152
153/// `turn/start` params.
154///
155/// `turn/start.providerRequestOptions` is deliberately absent: **RULED to stay
156/// off the published schema.** The schema is the contract, and a
157/// free-form-object node kind is revisited only if the experimental field
158/// graduates.
159#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
160#[serde(rename_all = "camelCase")]
161pub struct TurnStartParams {
162 /// The target session.
163 pub session_id: String,
164 /// The idempotency handle (UUIDv7). The fresh turn's `turnId` derives from
165 /// it.
166 pub command_id: String,
167 /// Ordered content parts; required and non-empty.
168 pub input: Vec<TurnInputPart>,
169 /// Disposition when a turn is already running; default `queue`.
170 #[serde(skip_serializing_if = "Option::is_none")]
171 pub if_busy: Option<IfBusy>,
172 /// Presentation form of the prompt for transcripts. Durable; carried on the
173 /// resulting user-message view item. Never model-visible.
174 #[serde(skip_serializing_if = "Option::is_none")]
175 pub display_text: Option<String>,
176 /// Reasoning tier sampled at submission for this turn.
177 #[serde(skip_serializing_if = "Option::is_none")]
178 pub reasoning_effort: Option<ReasoningEffort>,
179 /// This turn's token budget in tokens: an integer floor of 1, riding to
180 /// workflow-launch admission and inert when no workflow launches. Omitted
181 /// means no budget; 0 or a non-integer is invalid params, as is explicit
182 /// `null`. No wire upper bound beyond the integer type. Experimental: the
183 /// governing rules rules names and shape only, v1 membership stays open, so
184 /// the member ships off the stable bundle until a v1 ruling graduates it.
185 #[serde(
186 default,
187 deserialize_with = "crate::msp::method::lifecycle::deserialize_non_null_optional",
188 skip_serializing_if = "Option::is_none"
189 )]
190 pub token_budget: Option<u64>,
191 /// A sticky REPLACEMENT of the session's runtime workspace-root set,
192 /// binding at this turn's launch and persisting for subsequent turns until
193 /// replaced again — unlike `reasoningEffort`, which is this-turn-only. Same
194 /// shape and validation as `session/start.workspaceRoots`; invalid params
195 /// on an explicit `ifBusy: "steer"` submit and so is explicit `null`;
196 /// omitted means "unchanged", never "reset".
197 #[serde(
198 default,
199 deserialize_with = "crate::msp::method::lifecycle::deserialize_non_null_optional",
200 skip_serializing_if = "Option::is_none"
201 )]
202 pub workspace_roots: Option<Vec<String>>,
203 /// A queued `!` shell action riding this turn: the `!cmd` typed while a
204 /// turn runs, executed at the next model-call boundary before any later
205 /// steer. Exclusive with `text` and `skill` input; `input` may be empty
206 /// only when this member is present. Capability-gated on `userShell`: a
207 /// carrying turn on a connection without the grant fails `-32010
208 /// capabilityRequired`. Explicit `null` is invalid params (the
209 /// null-tolerant set is closed). A v1 stable member.
210 #[serde(
211 default,
212 deserialize_with = "crate::msp::method::lifecycle::deserialize_non_null_optional",
213 skip_serializing_if = "Option::is_none"
214 )]
215 pub user_shell: Option<TurnUserShell>,
216}
217
218/// What `turn/start` did with the input. Resolves OQ-H in v1: since `queue` is
219/// the default `ifBusy`, clients need to distinguish these without folding
220/// history.
221#[derive(Debug, Clone, PartialEq, Eq)]
222#[non_exhaustive]
223pub enum TurnStartDisposition {
224 /// A fresh foreground turn began.
225 Started,
226 /// Input parked; its turn — the ack's `turnId` — launches at the current
227 /// turn's terminal boundary.
228 Queued,
229 /// Absorbed by the running turn.
230 Steered,
231 /// A value from a newer host, kept verbatim so an older client decodes the
232 /// rest of the message. Excluded from the generated schema while the enum
233 /// stays declared open; never construct it with a known word.
234 Unknown(String),
235}
236
237/// `turn/start` result.
238#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
239#[serde(rename_all = "camelCase")]
240#[non_exhaustive]
241pub struct TurnStartResult {
242 /// Echoes the client's id.
243 pub command_id: String,
244 /// Admission status.
245 pub status: CommandStatus,
246 /// The turn that will carry (or absorbed) this input. Authoritative: always
247 /// take it from the ack rather than deriving it.
248 pub turn_id: String,
249 /// `true` iff `disposition` is `started`; retained as the boolean shorthand
250 /// — `disposition` is authoritative.
251 pub started_new_turn: bool,
252 /// What happened to the input.
253 pub disposition: TurnStartDisposition,
254}
255
256/// `turn/steer` params: exact-target steering into the currently running turn.
257#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
258#[serde(rename_all = "camelCase")]
259pub struct TurnSteerParams {
260 /// The target session.
261 pub session_id: String,
262 /// The idempotency handle (UUIDv7).
263 pub command_id: String,
264 /// The turn you believe is running. Closes the race where the turn
265 /// completes or is replaced between your read and your steer: input meant
266 /// for turn A can never leak into turn B. Any syntactically valid UUID: a
267 /// turn from an older session may carry a v4 or v5 id. A malformed id is
268 /// `invalidParams`; an id that is not the running turn is refused.
269 pub expected_turn_id: String,
270 /// Same content parts as `turn/start`.
271 pub input: Vec<TurnInputPart>,
272 /// Reasoning tier for the model calls this steer's input reaches. Applies
273 /// forward, never backward; absent means unspecified, not "reset".
274 #[serde(skip_serializing_if = "Option::is_none")]
275 pub reasoning_effort: Option<ReasoningEffort>,
276 /// This steer's token budget in tokens. Same vocabulary as the `turn/start`
277 /// member: an integer floor of 1, omitted means unspecified (never a reset
278 /// of the running turn's budget), 0 or a non-integer is invalid params, as
279 /// is explicit `null`. Experimental like its twin: v1 membership stays
280 /// open, so the member ships off the stable bundle until a v1 ruling
281 /// graduates it.
282 #[serde(
283 default,
284 deserialize_with = "crate::msp::method::lifecycle::deserialize_non_null_optional",
285 skip_serializing_if = "Option::is_none"
286 )]
287 pub token_budget: Option<u64>,
288}
289
290/// `turn/steer` result.
291#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
292#[serde(rename_all = "camelCase")]
293#[non_exhaustive]
294pub struct TurnSteerResult {
295 /// Echoes the client's id.
296 pub command_id: String,
297 /// Admission status.
298 pub status: CommandStatus,
299 /// The running turn that absorbed the input.
300 pub turn_id: String,
301}
302
303/// `turn/interrupt` params: the "user pressed stop" gesture, on the runtime's
304/// priority lane.
305#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
306#[serde(rename_all = "camelCase")]
307pub struct TurnInterruptParams {
308 /// The target session.
309 pub session_id: String,
310 /// The idempotency handle (UUIDv7).
311 pub command_id: String,
312 /// The exact turn to interrupt. Omit to target the session's current
313 /// foreground turn, resolved at admission; prefer passing the explicit id
314 /// when you have one. Any syntactically valid UUID: a turn from an older
315 /// session may carry a v4 or v5 id. A malformed id is `invalidParams`.
316 #[serde(skip_serializing_if = "Option::is_none")]
317 pub turn_id: Option<String>,
318 /// Pair a retract intent with the interrupt: if the turn is cancelled
319 /// before any assistant output committed, the submission is durably
320 /// retracted (view event `turn/retracted`) so the client may restore the
321 /// prompt text. A rejected retract does not undo the interrupt. Default
322 /// `false`.
323 #[serde(skip_serializing_if = "Option::is_none")]
324 pub retract: Option<bool>,
325}
326
327/// `turn/interrupt` result. Acceptance means the interrupt was admitted,
328/// **not** that the turn is already stopped: the turn is over when you fold its
329/// `turn/completed` with terminal `cancelled`.
330#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
331#[serde(rename_all = "camelCase")]
332#[non_exhaustive]
333pub struct TurnInterruptResult {
334 /// Echoes the client's id.
335 pub command_id: String,
336 /// Admission status.
337 pub status: CommandStatus,
338 /// The interrupted turn.
339 pub turn_id: String,
340}
341
342/// `turn/cancel` params: plain cancellation on the normal command lane. Same
343/// shape as `turn/interrupt`, **without** `retract` — pairing a retract with a
344/// plain cancel is durably rejected `not_paired_interrupt`.
345#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
346#[serde(rename_all = "camelCase")]
347pub struct TurnCancelParams {
348 /// The target session.
349 pub session_id: String,
350 /// The idempotency handle (UUIDv7).
351 pub command_id: String,
352 /// The exact turn to cancel; omit to target the current foreground turn.
353 /// Any syntactically valid UUID: a turn from an older session may carry a
354 /// v4 or v5 id. A malformed id is `invalidParams`.
355 #[serde(skip_serializing_if = "Option::is_none")]
356 pub turn_id: Option<String>,
357}
358
359/// `turn/cancel` result: identical envelope to `turn/interrupt`.
360#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
361#[serde(rename_all = "camelCase")]
362#[non_exhaustive]
363pub struct TurnCancelResult {
364 /// Echoes the client's id.
365 pub command_id: String,
366 /// Admission status.
367 pub status: CommandStatus,
368 /// The cancelled turn.
369 pub turn_id: String,
370}
371
372/// `turn/unqueue` params: reclaim a queued submit before it launches. It is
373/// **not** a stop — a reclaim that arrives after its target launched is durably
374/// rejected, never silently upgraded into a cancel.
375#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
376#[serde(rename_all = "camelCase")]
377pub struct TurnUnqueueParams {
378 /// The target session.
379 pub session_id: String,
380 /// The idempotency handle (UUIDv7).
381 pub command_id: String,
382 /// The queued turn to reclaim, exactly as the queueing `turn/start`'s ack
383 /// minted it and as snapshot `queuedTurns` lists it. Required, and never
384 /// "whichever is newest". Any syntactically valid UUID: a turn from an
385 /// older session may carry a v4 or v5 id. A malformed id is
386 /// `invalidParams`.
387 pub turn_id: String,
388}
389
390/// `turn/unqueue` result. Admission only — but for this command admission *is*
391/// the race: an admitted reclaim implies the turn will not launch. The
392/// authoritative removal is the `turn/unqueued` view event.
393#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
394#[serde(rename_all = "camelCase")]
395#[non_exhaustive]
396pub struct TurnUnqueueResult {
397 /// Echoes the client's id.
398 pub command_id: String,
399 /// Admission status.
400 pub status: CommandStatus,
401 /// The reclaimed turn.
402 pub turn_id: String,
403}