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