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
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}