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