Skip to main content

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}