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
3pub use input_part::TurnInputPart;
4use serde::Deserialize;
5use serde::Serialize;
6
7pub(crate) mod input_part;
8
9/// The ack `status`: `accepted` for every admitted command. `session/compact`
10/// is the one method that may additionally answer `noop`
11/// ([`crate::msp::method::runtime::CompactStatus`]); no other command uses
12/// another status.
13#[derive(Debug, Clone, PartialEq, Eq)]
14#[non_exhaustive]
15pub enum CommandStatus {
16    /// The command was admitted.
17    Accepted,
18    /// A value from a newer host, kept verbatim so an older client decodes the
19    /// rest of the message. Excluded from the generated schema while the enum
20    /// stays declared open; never construct it with a known word.
21    Unknown(String),
22}
23
24/// The reasoning-effort tier sampled at submission. The **same closed tier
25/// vocabulary** on both the fresh-turn and steer lanes, spelled identically;
26/// invalid tiers are invalid params. `none` is a tier of the vocabulary (ask
27/// for no reasoning), not a way to say "unset".
28#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
29#[serde(rename_all = "camelCase")]
30pub enum ReasoningEffort {
31    /// Ask for no reasoning.
32    None,
33    /// Minimal reasoning.
34    Minimal,
35    /// Low reasoning.
36    Low,
37    /// Medium reasoning.
38    Medium,
39    /// High reasoning.
40    High,
41    /// Extra-high reasoning.
42    Xhigh,
43    /// Max reasoning.
44    Max,
45    /// Ultra reasoning.
46    Ultra,
47}
48
49/// Disposition when a turn is already running. The wire default is `queue`: an
50/// SDK caller who has not looked at session state should not silently mutate an
51/// in-flight turn.
52#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
53#[serde(rename_all = "camelCase")]
54pub enum IfBusy {
55    /// Deliver the input as the next turn after the current one finishes.
56    Queue,
57    /// Inject the input into the running turn.
58    Steer,
59    /// Interrupt the running turn and start a fresh turn with this input.
60    Replace,
61}
62
63/// The queued `!` shell action a `turn/start` carries: the `!cmd` typed while a
64/// turn runs. The shell's command id derives from the carrying turn's
65/// `commandId`, exactly as the app's own queued submit does; the params'
66/// sibling `displayText` carries the `!…` presentation form.
67#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
68#[serde(rename_all = "camelCase")]
69pub struct TurnUserShell {
70    /// The shell command text, without the leading `!`.
71    pub command_text: String,
72}
73
74/// `turn/start` params.
75///
76/// `turn/start.providerRequestOptions` is deliberately absent: **RULED to stay
77/// off the published schema.** The schema is the contract, and a
78/// free-form-object node kind is revisited only if the experimental field
79/// graduates.
80#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
81#[serde(rename_all = "camelCase")]
82pub struct TurnStartParams {
83    /// The target session.
84    pub session_id: String,
85    /// The idempotency handle (UUIDv7). The fresh turn's `turnId` derives from
86    /// it.
87    pub command_id: String,
88    /// Ordered content parts; required and non-empty.
89    pub input: Vec<TurnInputPart>,
90    /// Disposition when a turn is already running; default `queue`.
91    #[serde(skip_serializing_if = "Option::is_none")]
92    pub if_busy: Option<IfBusy>,
93    /// Presentation form of the prompt for transcripts. Durable; carried on the
94    /// resulting user-message view item. Never model-visible.
95    #[serde(skip_serializing_if = "Option::is_none")]
96    pub display_text: Option<String>,
97    /// Reasoning tier sampled at submission for this turn.
98    #[serde(skip_serializing_if = "Option::is_none")]
99    pub reasoning_effort: Option<ReasoningEffort>,
100    /// This turn's token budget in tokens: an integer floor of 1, riding to
101    /// workflow-launch admission and inert when no workflow launches. Omitted
102    /// means no budget; 0 or a non-integer is invalid params, as is explicit
103    /// `null`. No wire upper bound beyond the integer type. Experimental: only
104    /// the name and shape are settled, not v1 membership, so the member ships
105    /// off the stable bundle until it graduates.
106    #[serde(
107        default,
108        deserialize_with = "crate::msp::method::lifecycle::deserialize_non_null_optional",
109        skip_serializing_if = "Option::is_none"
110    )]
111    pub token_budget: Option<u64>,
112    /// A sticky REPLACEMENT of the session's runtime workspace-root set,
113    /// binding at this turn's launch and persisting for subsequent turns until
114    /// replaced again — unlike `reasoningEffort`, which is this-turn-only. Same
115    /// shape and validation as `session/start.workspaceRoots`; invalid params
116    /// on an explicit `ifBusy: "steer"` submit and so is explicit `null`;
117    /// omitted means "unchanged", never "reset".
118    #[serde(
119        default,
120        deserialize_with = "crate::msp::method::lifecycle::deserialize_non_null_optional",
121        skip_serializing_if = "Option::is_none"
122    )]
123    pub workspace_roots: Option<Vec<String>>,
124    /// A queued `!` shell action riding this turn: the `!cmd` typed while a
125    /// turn runs, executed at the next model-call boundary before any later
126    /// steer. Exclusive with `text` and `skill` input; `input` may be empty
127    /// only when this member is present. Capability-gated on `userShell`: a
128    /// carrying turn on a connection without the grant fails `-32010
129    /// capabilityRequired`. Explicit `null` is invalid params (the
130    /// null-tolerant set is closed). A v1 stable member.
131    #[serde(
132        default,
133        deserialize_with = "crate::msp::method::lifecycle::deserialize_non_null_optional",
134        skip_serializing_if = "Option::is_none"
135    )]
136    pub user_shell: Option<TurnUserShell>,
137}
138
139/// What `turn/start` did with the input. Resolves OQ-H in v1: since `queue` is
140/// the default `ifBusy`, clients need to distinguish these without folding
141/// history.
142#[derive(Debug, Clone, PartialEq, Eq)]
143#[non_exhaustive]
144pub enum TurnStartDisposition {
145    /// A fresh foreground turn began.
146    Started,
147    /// Input parked; its turn — the ack's `turnId` — launches at the current
148    /// turn's terminal boundary.
149    Queued,
150    /// Absorbed by the running turn.
151    Steered,
152    /// A value from a newer host, kept verbatim so an older client decodes the
153    /// rest of the message. Excluded from the generated schema while the enum
154    /// stays declared open; never construct it with a known word.
155    Unknown(String),
156}
157
158/// `turn/start` result.
159#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
160#[serde(rename_all = "camelCase")]
161#[non_exhaustive]
162pub struct TurnStartResult {
163    /// Echoes the client's id.
164    pub command_id: String,
165    /// Admission status.
166    pub status: CommandStatus,
167    /// The turn that will carry (or absorbed) this input. Authoritative: always
168    /// take it from the ack rather than deriving it.
169    pub turn_id: String,
170    /// `true` iff `disposition` is `started`; retained as the boolean shorthand
171    /// — `disposition` is authoritative.
172    pub started_new_turn: bool,
173    /// What happened to the input.
174    pub disposition: TurnStartDisposition,
175    /// `queued` and `steered`: the queued input record's `recorded_at` in Unix
176    /// microseconds — the host clock the client's optimistic row must sort by,
177    /// so the row lands where the host's queue holds it. Present on a fresh
178    /// queued or steered admission via the enqueue arm (both append an inbox
179    /// record); absent on `started`, on hosts that predate the member, on
180    /// post-restart recovery replays, on the replace and park arms' Queued
181    /// acks, and on unopted connections. A client that sees no member falls
182    /// back to its wall clock (today's behavior).
183    #[serde(default, skip_serializing_if = "Option::is_none")]
184    pub queued_at_us: Option<u64>,
185}
186
187/// `turn/steer` params: exact-target steering into the currently running turn.
188#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
189#[serde(rename_all = "camelCase")]
190pub struct TurnSteerParams {
191    /// The target session.
192    pub session_id: String,
193    /// The idempotency handle (UUIDv7).
194    pub command_id: String,
195    /// The turn you believe is running. Closes the race where the turn
196    /// completes or is replaced between your read and your steer: input meant
197    /// for turn A can never leak into turn B. Any syntactically valid UUID: a
198    /// turn from an older session may carry a v4 or v5 id. A malformed id is
199    /// `invalidParams`; an id that is not the running turn is refused.
200    pub expected_turn_id: String,
201    /// Same content parts as `turn/start`.
202    pub input: Vec<TurnInputPart>,
203    /// Reasoning tier for the model calls this steer's input reaches. Applies
204    /// forward, never backward; absent means unspecified, not "reset".
205    #[serde(skip_serializing_if = "Option::is_none")]
206    pub reasoning_effort: Option<ReasoningEffort>,
207    /// This steer's token budget in tokens. Same vocabulary as the `turn/start`
208    /// member: an integer floor of 1, omitted means unspecified (never a reset
209    /// of the running turn's budget), 0 or a non-integer is invalid params, as
210    /// is explicit `null`. Experimental like its twin: v1 membership stays
211    /// open, so the member ships off the stable bundle until a v1 ruling
212    /// graduates it.
213    #[serde(
214        default,
215        deserialize_with = "crate::msp::method::lifecycle::deserialize_non_null_optional",
216        skip_serializing_if = "Option::is_none"
217    )]
218    pub token_budget: Option<u64>,
219}
220
221/// `turn/steer` result.
222#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
223#[serde(rename_all = "camelCase")]
224#[non_exhaustive]
225pub struct TurnSteerResult {
226    /// Echoes the client's id.
227    pub command_id: String,
228    /// Admission status.
229    pub status: CommandStatus,
230    /// The running turn that absorbed the input.
231    pub turn_id: String,
232}
233
234/// `turn/interrupt` params: the "user pressed stop" gesture, on the runtime's
235/// priority lane.
236#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
237#[serde(rename_all = "camelCase")]
238pub struct TurnInterruptParams {
239    /// The target session.
240    pub session_id: String,
241    /// The idempotency handle (UUIDv7).
242    pub command_id: String,
243    /// The exact turn to interrupt. Omit to target the session's current
244    /// foreground turn, resolved at admission; prefer passing the explicit id
245    /// when you have one. Any syntactically valid UUID: a turn from an older
246    /// session may carry a v4 or v5 id. A malformed id is `invalidParams`.
247    #[serde(skip_serializing_if = "Option::is_none")]
248    pub turn_id: Option<String>,
249    /// Pair a retract intent with the interrupt: if the turn is cancelled
250    /// before any assistant output committed, the submission is durably
251    /// retracted (view event `turn/retracted`) so the client may restore the
252    /// prompt text. A rejected retract does not undo the interrupt. Default
253    /// `false`.
254    #[serde(skip_serializing_if = "Option::is_none")]
255    pub retract: Option<bool>,
256}
257
258/// `turn/interrupt` result. Acceptance means the interrupt was admitted,
259/// **not** that the turn is already stopped: the turn is over when you fold its
260/// `turn/completed` with terminal `cancelled`.
261#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
262#[serde(rename_all = "camelCase")]
263#[non_exhaustive]
264pub struct TurnInterruptResult {
265    /// Echoes the client's id.
266    pub command_id: String,
267    /// Admission status.
268    pub status: CommandStatus,
269    /// The interrupted turn.
270    pub turn_id: String,
271}
272
273/// `turn/cancel` params: plain cancellation on the normal command lane. Same
274/// shape as `turn/interrupt`, **without** `retract` — pairing a retract with a
275/// plain cancel is durably rejected `not_paired_interrupt`.
276#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
277#[serde(rename_all = "camelCase")]
278pub struct TurnCancelParams {
279    /// The target session.
280    pub session_id: String,
281    /// The idempotency handle (UUIDv7).
282    pub command_id: String,
283    /// The exact turn to cancel; omit to target the current foreground turn.
284    /// Any syntactically valid UUID: a turn from an older session may carry a
285    /// v4 or v5 id. A malformed id is `invalidParams`.
286    #[serde(skip_serializing_if = "Option::is_none")]
287    pub turn_id: Option<String>,
288}
289
290/// `turn/cancel` result: identical envelope to `turn/interrupt`.
291#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
292#[serde(rename_all = "camelCase")]
293#[non_exhaustive]
294pub struct TurnCancelResult {
295    /// Echoes the client's id.
296    pub command_id: String,
297    /// Admission status.
298    pub status: CommandStatus,
299    /// The cancelled turn.
300    pub turn_id: String,
301}
302
303/// `turn/unqueue` params: reclaim a queued submit before it launches. It is
304/// **not** a stop — a reclaim that arrives after its target launched is durably
305/// rejected, never silently upgraded into a cancel.
306#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
307#[serde(rename_all = "camelCase")]
308pub struct TurnUnqueueParams {
309    /// The target session.
310    pub session_id: String,
311    /// The idempotency handle (UUIDv7).
312    pub command_id: String,
313    /// The queued turn to reclaim, exactly as the queueing `turn/start`'s ack
314    /// minted it and as snapshot `queuedTurns` lists it. Required, and never
315    /// "whichever is newest". Any syntactically valid UUID: a turn from an
316    /// older session may carry a v4 or v5 id. A malformed id is
317    /// `invalidParams`.
318    pub turn_id: String,
319}
320
321/// `turn/unqueue` result. Admission only — but for this command admission *is*
322/// the race: an admitted reclaim implies the turn will not launch. The
323/// authoritative removal is the `turn/unqueued` view event.
324#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
325#[serde(rename_all = "camelCase")]
326#[non_exhaustive]
327pub struct TurnUnqueueResult {
328    /// Echoes the client's id.
329    pub command_id: String,
330    /// Admission status.
331    pub status: CommandStatus,
332    /// The reclaimed turn.
333    pub turn_id: String,
334}