Skip to main content

muse_code_sdk/msp/view/
user_input.rs

1// @generated from the MSP stable schema and protocol sources; do not edit by hand.
2
3use crate::msp::view::SourceRange;
4use serde::Deserialize;
5use serde::Serialize;
6
7mod catch_all;
8
9/// Full params shared by `userInput/request` and `userInput/requested`.
10#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
11#[serde(rename_all = "camelCase")]
12#[non_exhaustive]
13pub struct UserInputRequestParams {
14    /// The session that owns the prompt.
15    pub session_id: String,
16    /// The prompt's stable id. Pass it to `userInput/answer`,
17    /// `userInput/cancel`, `userInput/clarify` and `userInput/interrupt`, and
18    /// use it to match the later `userInput/settled`.
19    pub user_input_id: String,
20    /// The turn whose tool call is waiting on this prompt.
21    pub turn_id: String,
22    /// The `toolCall` view item of the tool call waiting on this prompt.
23    pub item_id: String,
24    /// The provider's id for the tool call that opened the prompt.
25    pub tool_call_id: String,
26    /// The name of the tool that opened the prompt.
27    pub tool_name: String,
28    /// The cursor of the `userInput/requested` event for this prompt. A client
29    /// that missed the request can read the same payload at this cursor with
30    /// `view/page`.
31    pub view_cursor: String,
32    /// The stored records this prompt was folded from, when sent: an opaque
33    /// token clients must not interpret.
34    #[serde(skip_serializing_if = "Option::is_none")]
35    pub source_range: Option<SourceRange>,
36    /// The questions to ask, one to three, in order.
37    pub questions: Vec<UserInputQuestion>,
38    /// The auto-resolution time per question, in milliseconds: a prompt nobody
39    /// engages with settles as `timedOut` after this value times the number of
40    /// questions.
41    #[serde(skip_serializing_if = "Option::is_none")]
42    pub auto_resolution_ms: Option<u64>,
43}
44
45/// `userInput/settled` params: the first durable prompt settlement.
46#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
47#[serde(rename_all = "camelCase")]
48#[non_exhaustive]
49pub struct UserInputSettledParams {
50    /// The session that owns the prompt.
51    pub session_id: String,
52    /// This event's view cursor: opaque, and strictly increasing within the
53    /// session.
54    pub view_cursor: String,
55    /// The stored records this event was folded from: an opaque token clients
56    /// must not interpret.
57    pub source_range: SourceRange,
58    /// The prompt that settled. Accept a settlement even for a prompt whose
59    /// request you never saw.
60    pub user_input_id: String,
61    /// How the prompt ended.
62    pub outcome: UserInputOutcome,
63    /// The recorded answers: one per question for `answered`, any confirmed
64    /// partial answers for `interrupted`, and empty for every other outcome.
65    pub answers: Vec<UserInputAnswer>,
66    /// The user's free-form clarification when the outcome is `clarified`;
67    /// `null` otherwise.
68    pub clarification: Option<UserInputClarification>,
69    /// The reason, when one applies: the optional reason given with a cancel,
70    /// or why an `aborted` prompt was closed; `null` otherwise.
71    pub reason: Option<String>,
72    /// The `commandId` of the client command that settled the prompt; `null`
73    /// when no command did, for example after a timeout or an abort.
74    pub decided_by_command_id: Option<String>,
75    /// The decision time as RFC3339, projected from the durable settlement
76    /// record's own stamp: always present on the wire (schema-required,
77    /// `null`-able); decoders still tolerate its absence, and current hosts
78    /// always populate it.
79    #[serde(default)]
80    pub decided_at: Option<String>,
81}
82
83/// One question in a user-input prompt.
84#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
85#[serde(rename_all = "camelCase")]
86#[non_exhaustive]
87pub struct UserInputQuestion {
88    /// The question's id, unique within the prompt and at most 64 characters.
89    /// An answer names it in `questionId`.
90    pub id: String,
91    /// A short title for the question, at most 12 characters.
92    pub header: String,
93    /// The full question text to show the user.
94    pub question: String,
95    /// Whether the user picks one option or several.
96    pub selection: UserInputSelection,
97    /// The options offered, two or three, in order.
98    pub options: Vec<UserInputOption>,
99}
100
101/// How many options the user may pick for a question.
102#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
103#[serde(rename_all = "camelCase")]
104#[non_exhaustive]
105pub struct UserInputSelection {
106    /// `single` or `multiple`: whether an answer selects one option or several.
107    pub mode: UserInputSelectionMode,
108    /// The minimum selection count for a `multiple` answer. Sent only in
109    /// `multiple` mode; when absent the minimum is 1.
110    #[serde(skip_serializing_if = "Option::is_none")]
111    pub min_selections: Option<usize>,
112    /// The most options the user may pick. Sent only in `multiple` mode; when
113    /// absent the maximum is the number of options.
114    #[serde(skip_serializing_if = "Option::is_none")]
115    pub max_selections: Option<usize>,
116}
117
118/// Whether a question takes one option or several.
119#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
120#[serde(rename_all = "camelCase")]
121pub enum UserInputSelectionMode {
122    /// `single`: the user picks one option, answered with `selectedLabel`, or
123    /// gives a free-text answer instead.
124    Single,
125    /// `multiple`: an answer may select several options, within the
126    /// question's bounds. Options never carry a preview in this mode.
127    Multiple,
128}
129
130/// One option offered for a question.
131#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
132#[serde(rename_all = "camelCase")]
133#[non_exhaustive]
134pub struct UserInputOption {
135    /// The option's text, at most 80 characters and unique within its question;
136    /// an answer selects the option by this exact label.
137    pub label: String,
138    /// An optional longer explanation of the option, at most 240 characters.
139    #[serde(skip_serializing_if = "Option::is_none")]
140    pub description: Option<String>,
141    /// An optional rich preview of the option, present only on single-select
142    /// questions.
143    #[serde(skip_serializing_if = "Option::is_none")]
144    pub preview: Option<UserInputOptionPreview>,
145}
146
147/// Rich content a client can show for an option. Only single-select questions
148/// carry previews.
149#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
150#[serde(rename_all = "camelCase")]
151#[non_exhaustive]
152pub struct UserInputOptionPreview {
153    /// The content format, for example `markdown`.
154    pub format: String,
155    /// The preview content in that format, at most 2000 characters.
156    pub content: String,
157}
158
159/// One question's answer, as sent in `userInput/answer` or
160/// `userInput/interrupt` and as recorded in `userInput/settled`.
161#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
162#[serde(rename_all = "camelCase")]
163pub struct UserInputAnswer {
164    /// The `id` of the question this answers.
165    pub question_id: String,
166    /// The label of the chosen option, for a `single` question.
167    #[serde(skip_serializing_if = "Option::is_none")]
168    pub selected_label: Option<String>,
169    /// The labels of the chosen options for a `multiple` question, within its
170    /// selection bounds; omitted when empty.
171    #[serde(default, skip_serializing_if = "Vec::is_empty")]
172    pub selected_labels: Vec<String>,
173    /// A free-form answer, at most 500 characters.
174    #[serde(skip_serializing_if = "Option::is_none")]
175    pub free_text: Option<String>,
176    /// An optional comment the user adds to the answer, at most 500 characters.
177    #[serde(skip_serializing_if = "Option::is_none")]
178    pub note: Option<String>,
179}
180
181/// A free-form reply the user gives instead of choosing from the options; the
182/// model reads it and decides again.
183#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
184#[serde(rename_all = "camelCase")]
185pub struct UserInputClarification {
186    /// The content format. `text` is the only value today, and more may be
187    /// added.
188    pub format: String,
189    /// The clarification text, at most 500 characters.
190    pub content: String,
191}
192
193/// How a user-input prompt settled. More values may be added, so handle values
194/// you do not recognize.
195#[derive(Debug, Clone, PartialEq, Eq)]
196#[non_exhaustive]
197pub enum UserInputOutcome {
198    /// `answered`: the user answered every question.
199    Answered,
200    /// `cancelled`: the user declined to answer.
201    Cancelled,
202    /// `interrupted`: the turn was interrupted while the prompt was open. If a
203    /// `userInput/interrupt` named this prompt, its confirmed answers are in
204    /// `answers`.
205    Interrupted,
206    /// `clarified`: the user replied with a free-form clarification instead of
207    /// choosing options.
208    Clarified,
209    /// `timedOut`: the prompt's auto-resolution countdown ran out before anyone
210    /// answered.
211    TimedOut,
212    /// `aborted`: the host closed the prompt without an answer, for example
213    /// when the run was torn down; `reason` says why.
214    Aborted,
215    /// A value from a newer host, kept verbatim so an older client decodes the
216    /// rest of the message. Never construct it with a known word.
217    Unknown(String),
218}