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}