Skip to main content

muse_code_sdk/msp/
error.rs

1// @generated from the MSP stable schema and protocol sources; do not edit by hand.
2
3use crate::msp::capability::CapabilityName;
4use crate::msp::envelope::JsonObject;
5pub use kind::ErrorKind;
6pub use registry::ErrorCode;
7use serde::Deserialize;
8use serde::Serialize;
9
10pub(crate) mod kind;
11pub(crate) mod registry;
12
13/// Identifies one requirement of an approval: for a `shell` approval, one
14/// stage. A client sends it back as `requirementId` in `approval/decide`, and a
15/// stale-requirement error names the current one.
16#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
17#[serde(rename_all = "camelCase")]
18pub struct ApprovalRequirementRef {
19    /// The approval this requirement belongs to.
20    pub approval_id: String,
21    /// The requirement's index within the approval, counting from 0; an
22    /// approval with a single requirement uses 0.
23    pub source_index: usize,
24}
25
26/// Winning terminal returned to a losing `approval/decide` command.
27#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
28#[serde(rename_all = "camelCase")]
29#[non_exhaustive]
30pub struct ApprovalResolutionSummary {
31    /// The winning decision, as an `approval/resolved` decision value such as
32    /// `approved` or `abort`.
33    pub decision: String,
34    /// Who made the winning decision, such as `user`, `policy` or `llmJudge`.
35    pub resolved_by: String,
36    /// The view cursor of the winning `approval/resolved` event.
37    pub view_cursor: String,
38}
39
40/// Winning terminal returned to a late user-input command.
41#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
42#[serde(rename_all = "camelCase")]
43#[non_exhaustive]
44pub struct UserInputSettlementSummary {
45    /// How the prompt settled, as a `userInput/settled` outcome value such as
46    /// `answered` or `timedOut`.
47    pub outcome: String,
48    /// The view cursor of the `userInput/settled` event that recorded the
49    /// settlement.
50    pub view_cursor: String,
51}
52
53/// Winning terminal returned to a losing `admission/decide` command:
54/// `resolvedBy` is omitted on timeout.
55#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
56#[serde(rename_all = "camelCase")]
57#[non_exhaustive]
58pub struct AdmissionResolutionSummary {
59    /// The winning decision, such as `allow_once` or `timedOut`.
60    pub decision: String,
61    /// Who made the winning decision; absent when no person decided, for
62    /// example a timeout, an automatic allow, or a cancelled or retired
63    /// request.
64    #[serde(default, skip_serializing_if = "Option::is_none")]
65    pub resolved_by: Option<String>,
66    /// The view cursor of the winning `admission/resolved` event.
67    pub view_cursor: String,
68}
69
70/// Deserialize a PRESENT member into the presence-tracking double-`Option`:
71/// serde only calls this when the key exists, so an explicit JSON null becomes
72/// `Some(None)` while an absent key stays `None` via `#[serde(default)]`.
73/// Serialization is symmetric — `Some(None)` emits the explicit null, `None`
74/// skips the key.
75fn present_member<'de, D, T>(deserializer: D) -> Result<Option<Option<T>>, D::Error>
76where
77    D: serde::Deserializer<'de>,
78    T: Deserialize<'de>,
79{
80    Option::<T>::deserialize(deserializer).map(Some)
81}
82
83/// The optional `error.data` object. All members additive-optional; `kind` is
84/// always present when `data` is.
85#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
86#[serde(rename_all = "camelCase")]
87#[non_exhaustive]
88pub struct ErrorData {
89    /// The stable camelCase category clients branch on.
90    pub kind: ErrorKind,
91    /// Whether retrying can succeed (e.g. `overloaded`). When present,
92    /// overrides the error table row's `retryable` default for this code.
93    #[serde(skip_serializing_if = "Option::is_none")]
94    pub retryable: Option<bool>,
95    /// On `experimentalRequired` errors, the name of the experimental method,
96    /// field or variant the request used, for example
97    /// `turn/start.providerRequestOptions`.
98    #[serde(skip_serializing_if = "Option::is_none")]
99    pub descriptor: Option<String>,
100    /// The missing capability, on `capabilityRequired` errors. Typed on the
101    /// grantable registry, so the experimental-only `rawLog` joins the stable
102    /// domain as an additive open-enum extension when it graduates.
103    #[serde(skip_serializing_if = "Option::is_none")]
104    pub capability: Option<CapabilityName>,
105    /// The rejected command's identifier, on `commandRejected` errors. The
106    /// ratified v1 contract pairs it with `reason`, so a client can settle the
107    /// exact command it sent without parsing the message string.
108    #[serde(skip_serializing_if = "Option::is_none")]
109    pub command_id: Option<String>,
110    /// Failure detail vocabulary (e.g. `"missingAnchor"` on `notFound` for a
111    /// missing view-cursor anchor).
112    #[serde(skip_serializing_if = "Option::is_none")]
113    pub reason: Option<String>,
114    /// The exceeded byte limit, on `inputTooLarge` errors.
115    #[serde(skip_serializing_if = "Option::is_none")]
116    pub limit_bytes: Option<u64>,
117    /// The blocked view position on `pageEventTooLarge` errors.
118    #[serde(skip_serializing_if = "Option::is_none")]
119    pub view_cursor: Option<String>,
120    /// The item whose stored output was requested, on the `item/readOutput`
121    /// arms (`notFound`, `outputUnavailable`, and the misaligned-offset
122    /// `invalidParams`).
123    #[serde(skip_serializing_if = "Option::is_none")]
124    pub item_id: Option<String>,
125    /// The requested `outputRef.id`, on the same `item/readOutput` arms.
126    #[serde(skip_serializing_if = "Option::is_none")]
127    pub output_ref: Option<String>,
128    /// The stored output's availability on `outputUnavailable` — the durable
129    /// `ToolOutputAvailability` value, read-time-derived when the durable
130    /// record still says `available`.
131    #[serde(skip_serializing_if = "Option::is_none")]
132    pub availability: Option<String>,
133    /// The next provable UTF-8 boundary on a misaligned text-media
134    /// `item/readOutput` read: absent when no boundary is provable from the
135    /// stored bytes ahead.
136    #[serde(skip_serializing_if = "Option::is_none")]
137    pub aligned_next_offset: Option<u64>,
138    /// The configured command-admission bound, on `backpressured` errors.
139    #[serde(skip_serializing_if = "Option::is_none")]
140    pub capacity: Option<u64>,
141    /// Free-form additive detail.
142    #[serde(skip_serializing_if = "Option::is_none")]
143    pub details: Option<JsonObject>,
144    /// Session identity on errors whose lookup is session-scoped.
145    #[serde(skip_serializing_if = "Option::is_none")]
146    pub session_id: Option<String>,
147    /// The original recovery-dependent construction's coherent observation.
148    /// An absent or unusable observation establishes no supported recovery.
149    #[serde(
150        default,
151        deserialize_with = "crate::msp::method::lifecycle::deserialize_optional_recovery_observation",
152        skip_serializing_if = "Option::is_none"
153    )]
154    pub recovery_observation: Option<crate::msp::method::lifecycle::RecoveryObservation>,
155    /// The rejected skill selector on `skillNotFound`.
156    #[serde(skip_serializing_if = "Option::is_none")]
157    pub selector: Option<String>,
158    /// The rejected marketplace name on `marketplaceNotFound` and
159    /// `marketplaceAlreadyExists`; the rejected plugin name on
160    /// `pluginNotFound`.
161    #[serde(skip_serializing_if = "Option::is_none")]
162    pub name: Option<String>,
163    /// The store on `pluginNotFound`.
164    #[serde(skip_serializing_if = "Option::is_none")]
165    pub marketplace: Option<String>,
166    /// The rejected upload id on `uploadNotFound`.
167    #[serde(skip_serializing_if = "Option::is_none")]
168    pub upload_id: Option<String>,
169    /// The oldest servable view position on `viewTruncated`; served as an
170    /// explicit `null` when nothing before the head is servable — the null is
171    /// present on the wire, never a dropped key.
172    #[serde(
173        default,
174        skip_serializing_if = "Option::is_none",
175        deserialize_with = "present_member"
176    )]
177    pub earliest_cursor: Option<Option<String>>,
178    /// The rejected anchor value on `notFound`/`missingAnchor` and the `-32042`
179    /// boundary arms; on `-32042` it is served as an explicit `null` when the
180    /// request named no concrete anchor.
181    #[serde(
182        default,
183        skip_serializing_if = "Option::is_none",
184        deserialize_with = "present_member"
185    )]
186    pub anchor: Option<Option<String>>,
187    /// The latest installed boundary's view cursor on the `-32042` arms —
188    /// always present in the `-32042` JSON and explicitly `null` when no
189    /// boundary exists.
190    #[serde(
191        default,
192        skip_serializing_if = "Option::is_none",
193        deserialize_with = "present_member"
194    )]
195    pub latest_boundary_cursor: Option<Option<String>>,
196    /// Rejected inclusive fork boundary on `forkBoundaryInvalid`.
197    #[serde(skip_serializing_if = "Option::is_none")]
198    pub last_turn_id: Option<String>,
199    /// The branch-seed path the host read before rejecting, on
200    /// branch-validation rejections: one of `runtime_checkpoint_tail`,
201    /// `runtime_full_replay`, `legacy_session_data` — the durable branch-seed
202    /// vocabulary, so the client cites the real seed decision instead of
203    /// guessing at a stale binary.
204    #[serde(skip_serializing_if = "Option::is_none")]
205    pub seed_path: Option<String>,
206    /// Why the branch seed did not use a checkpoint, on the same arms:
207    /// one of `no_usable_checkpoint`, `unsupported_checkpoint_shape`,
208    /// `checkpoint_has_model_visible_tail`, `checkpoint_missing_suffix`;
209    /// absent when the seed used a checkpoint or no fallback was recorded.
210    #[serde(skip_serializing_if = "Option::is_none")]
211    pub seed_fallback_reason: Option<String>,
212    /// Candidate retained paths on `sessionAmbiguous`.
213    #[serde(skip_serializing_if = "Option::is_none")]
214    pub paths: Option<Vec<String>>,
215    /// Approval id on approval errors.
216    #[serde(skip_serializing_if = "Option::is_none")]
217    pub approval_id: Option<String>,
218    /// Winning resolution on `approvalAlreadyResolved`.
219    #[serde(skip_serializing_if = "Option::is_none")]
220    pub resolution: Option<ApprovalResolutionSummary>,
221    /// Current stage token on `approvalRequirementStale`.
222    #[serde(skip_serializing_if = "Option::is_none")]
223    pub current_requirement_id: Option<ApprovalRequirementRef>,
224    /// Rejected server-minted choice on `approvalChoiceInvalid`.
225    #[serde(skip_serializing_if = "Option::is_none")]
226    pub choice_id: Option<String>,
227    /// Prompt identity on user-input errors.
228    #[serde(skip_serializing_if = "Option::is_none")]
229    pub user_input_id: Option<String>,
230    /// Winning settlement on `userInputAlreadySettled`.
231    #[serde(skip_serializing_if = "Option::is_none")]
232    pub settlement: Option<UserInputSettlementSummary>,
233    /// Admission identity on admission errors.
234    #[serde(skip_serializing_if = "Option::is_none")]
235    pub admission_id: Option<String>,
236    /// Winning resolution on `admissionAlreadyResolved`.
237    #[serde(skip_serializing_if = "Option::is_none")]
238    pub admission_resolution: Option<AdmissionResolutionSummary>,
239    /// The rejected raw-log stream, on the anchor arms (`missingAnchor`,
240    /// `prunedPrefix`, `unknownStream`).
241    #[serde(skip_serializing_if = "Option::is_none")]
242    pub stream: Option<crate::msp::view::StreamRef>,
243    /// The rejected raw-log anchor, on `missingAnchor`, `prunedPrefix`,
244    /// and `wrongStream`.
245    #[serde(skip_serializing_if = "Option::is_none")]
246    pub after: Option<crate::msp::view::RecordPosition>,
247    /// The earliest readable position, on `prunedPrefix`.
248    #[serde(skip_serializing_if = "Option::is_none")]
249    pub next_available: Option<crate::msp::view::RecordPosition>,
250    /// The requested stream, on `wrongStream`.
251    #[serde(skip_serializing_if = "Option::is_none")]
252    pub requested_stream: Option<crate::msp::view::StreamRef>,
253    /// The stream the anchor's id actually belongs to, on `wrongStream`.
254    #[serde(skip_serializing_if = "Option::is_none")]
255    pub cursor_stream: Option<crate::msp::view::StreamRef>,
256    /// The unregistered projection name, on `unknownProjection`.
257    #[serde(skip_serializing_if = "Option::is_none")]
258    pub projection: Option<String>,
259    /// The subject repository path, on `workspaceNotTrusted`.
260    #[serde(skip_serializing_if = "Option::is_none")]
261    pub path: Option<String>,
262    /// The rejected settings key path, on the `settings/writeValue` and
263    /// `settings/writeMany` arms: the structural `-32602 invalidParams` shape
264    /// and the `-32030` managed-denial block. File spelling verbatim, like the
265    /// request's `keyPath`.
266    #[serde(skip_serializing_if = "Option::is_none")]
267    pub key_path: Option<String>,
268    /// The rejected edit's index into the `settings/writeMany` `edits`
269    /// array, on the same arms; absent on `settings/writeValue`, which
270    /// carries no edit list.
271    #[serde(skip_serializing_if = "Option::is_none")]
272    pub index: Option<u64>,
273    /// Every too-wide axis with its requested and ceiling values, on
274    /// `limitsAboveMax`.
275    #[serde(skip_serializing_if = "Option::is_none")]
276    pub axes: Option<Vec<crate::msp::method::limits::LimitsAboveMaxAxis>>,
277}
278
279impl ErrorData {
280    /// A `kind`-only payload with every optional field `None` — the one
281    /// constructor call sites extend with struct-update syntax, so an
282    /// additive SS field touches this file alone, never every literal.
283    #[must_use]
284    pub const fn new(kind: ErrorKind) -> Self {
285        Self {
286            kind,
287            retryable: None,
288            descriptor: None,
289            capability: None,
290            command_id: None,
291            reason: None,
292            limit_bytes: None,
293            view_cursor: None,
294            item_id: None,
295            output_ref: None,
296            availability: None,
297            aligned_next_offset: None,
298            capacity: None,
299            details: None,
300            session_id: None,
301            recovery_observation: None,
302            selector: None,
303            name: None,
304            marketplace: None,
305            upload_id: None,
306            earliest_cursor: None,
307            anchor: None,
308            latest_boundary_cursor: None,
309            last_turn_id: None,
310            seed_path: None,
311            seed_fallback_reason: None,
312            paths: None,
313            approval_id: None,
314            resolution: None,
315            current_requirement_id: None,
316            choice_id: None,
317            user_input_id: None,
318            settlement: None,
319            admission_id: None,
320            admission_resolution: None,
321            stream: None,
322            after: None,
323            next_available: None,
324            requested_stream: None,
325            cursor_stream: None,
326            projection: None,
327            path: None,
328            key_path: None,
329            index: None,
330            axes: None,
331        }
332    }
333}
334
335/// The `error` member of an error response.
336#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
337#[serde(rename_all = "camelCase")]
338#[non_exhaustive]
339pub struct ErrorObject {
340    /// Registry code. Typed as a plain integer on the wire; the value domain is
341    /// the registry below.
342    pub code: i64,
343    /// Human-readable message. Never a branch point.
344    pub message: String,
345    /// Structured detail; carries `kind` when present.
346    #[serde(skip_serializing_if = "Option::is_none")]
347    pub data: Option<Box<ErrorData>>,
348}