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}