Skip to main content

muse_code_sdk/msp/view/
event.rs

1// @generated from the MSP stable schema and protocol sources; do not edit by hand.
2
3use crate::msp::view::SourceRange;
4use crate::msp::view::item::Item;
5use crate::msp::view::state::TokenUsage;
6use serde::Deserialize;
7use serde::Serialize;
8
9mod catch_all;
10
11/// `turn/started` params: a foreground turn began running — fresh submits
12/// immediately, queued submits at their launch boundary, never steered submits.
13#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
14#[serde(rename_all = "camelCase")]
15#[non_exhaustive]
16pub struct TurnStartedParams {
17    /// The owning session.
18    pub session_id: String,
19    /// Opaque, strictly monotonic view cursor.
20    pub view_cursor: String,
21    /// The durable records this event folded from.
22    pub source_range: SourceRange,
23    /// The started turn.
24    pub turn_id: String,
25    /// The submitting command; `turnId == commandId` for fresh turns.
26    pub command_id: String,
27}
28
29/// `turn/completed` params: the run's durable terminal record landed.
30#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
31#[serde(rename_all = "camelCase")]
32#[non_exhaustive]
33pub struct TurnCompletedParams {
34    /// The owning session.
35    pub session_id: String,
36    /// Opaque, strictly monotonic view cursor.
37    pub view_cursor: String,
38    /// The durable records this event folded from.
39    pub source_range: SourceRange,
40    /// The terminated turn.
41    pub turn_id: String,
42    /// The turn terminal (open enum).
43    pub terminal: TurnTerminal,
44    /// The runtime's free-text terminal reason, verbatim. Display and
45    /// diagnostics only; never branch on it.
46    #[serde(skip_serializing_if = "Option::is_none")]
47    pub reason: Option<String>,
48    /// Turn duration; absent means unmeasured, never fabricated.
49    #[serde(skip_serializing_if = "Option::is_none")]
50    pub duration_ms: Option<u64>,
51    /// Time to first token, when measured.
52    #[serde(skip_serializing_if = "Option::is_none")]
53    pub time_to_first_token_ms: Option<u64>,
54    /// The turn's aggregate token usage, summed across the turn's model
55    /// completions (same shape as `session/tokenUsage.usage`).
56    #[serde(skip_serializing_if = "Option::is_none")]
57    pub usage: Option<TokenUsage>,
58    /// Present when `terminal` is `"failed"`, except on a synthesized
59    /// host-death terminal, which carries `reason` instead: mid-turn failures
60    /// reach the client here — never as a JSON-RPC error.
61    #[serde(skip_serializing_if = "Option::is_none")]
62    pub error: Option<TurnError>,
63}
64
65/// `turn/retracted` params: an interrupt-paired retract durably settled,
66/// accepted or declined. On `"accepted"` the retracted user-message item is
67/// re-emitted via `item/updated` with `retracted: true`; on `"declined"` the
68/// client folds the legacy declined rollback instead and no item is re-emitted.
69#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
70#[serde(rename_all = "camelCase")]
71#[non_exhaustive]
72pub struct TurnRetractedParams {
73    /// The owning session.
74    pub session_id: String,
75    /// Opaque, strictly monotonic view cursor.
76    pub view_cursor: String,
77    /// The durable records this event folded from.
78    pub source_range: SourceRange,
79    /// The turn whose submission was retracted.
80    pub turn_id: String,
81    /// The retracted submission's command id.
82    pub command_id: String,
83    /// The retract settlement outcome. Additive-optional: absent reads as
84    /// `"accepted"` — pre-feature hosts emit the event only for accepted
85    /// retracts — and so does an unrecognized value.
86    #[serde(skip_serializing_if = "Option::is_none")]
87    pub outcome: Option<RetractOutcome>,
88}
89
90/// A `turn/retracted` settlement outcome. Open enum: decode is tolerant — a
91/// value outside the list reads as `Accepted` (the event's historical meaning —
92/// pre-feature hosts emit it only for accepted retracts), never fails. The
93/// bundle keeps enumerating the known values for codegen and docs.
94#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)]
95#[serde(rename_all = "camelCase")]
96#[non_exhaustive]
97pub enum RetractOutcome {
98    /// The retract was durably accepted; the submission was retracted.
99    Accepted,
100    /// The retract settled rejected (the submission stood); the client
101    /// folds the legacy declined rollback.
102    Declined,
103}
104
105impl<'de> Deserialize<'de> for RetractOutcome {
106    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
107    where
108        D: serde::de::Deserializer<'de>,
109    {
110        let value = String::deserialize(deserializer)?;
111        Ok(match value.as_str() {
112            "declined" => Self::Declined,
113            _ => Self::Accepted,
114        })
115    }
116}
117
118/// `turn/retryScheduled` params: a durable turn retry-scheduled fact folded —
119/// the failing model attempt's scheduled retry is observable BEFORE the turn
120/// terminates, so a streaming client can render "attempt N/M · retrying in Ss ·
121/// reason" instead of dead air. Non-terminal: it never resolves a turn-wait.
122/// The delay is the recorded scheduled backoff, never an absolute fire time —
123/// clients derive any countdown locally. `sourceRange` cites the session
124/// stream's mirror of the task-lifecycle record.
125#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
126#[serde(rename_all = "camelCase")]
127#[non_exhaustive]
128pub struct TurnRetryScheduledParams {
129    /// The owning session.
130    pub session_id: String,
131    /// Opaque, strictly monotonic view cursor.
132    pub view_cursor: String,
133    /// The durable record this event folded from (the session stream's
134    /// mirror of the retry-scheduled task status; `first == last`).
135    pub source_range: SourceRange,
136    /// The running turn whose model attempt is being retried.
137    pub turn_id: String,
138    /// The attempt that failed (producer-normalized, >= 1).
139    pub attempt: u32,
140    /// The attempt about to run (producer contract: attempt < nextAttempt
141    /// <= maxAttempts; not a schema constraint).
142    pub next_attempt: u32,
143    /// The turn's model-retry chain bound.
144    pub max_attempts: u32,
145    /// The scheduled backoff delay in milliseconds, verbatim from the
146    /// durable fact.
147    pub retry_delay_ms: u64,
148    /// The recorded stopping reason through the shared task-detail
149    /// normalization (non-empty; capped at 160 characters).
150    pub reason: String,
151    /// The failing model attempt's provider system, verbatim — e.g. `"meta"`.
152    /// Absent when no model-attempt facet precedes the retry status on the task
153    /// (old logs).
154    #[serde(skip_serializing_if = "Option::is_none")]
155    pub system: Option<String>,
156    /// The failing model attempt's durable kind, verbatim — a plain string: the
157    /// durable vocabulary is open-ended.
158    #[serde(skip_serializing_if = "Option::is_none")]
159    pub error_kind: Option<String>,
160    /// The failing model attempt's HTTP status.
161    #[serde(skip_serializing_if = "Option::is_none")]
162    pub http_status: Option<u16>,
163}
164
165/// `turn/modelRetryScheduled` params: a durable model-stream retry-scheduled
166/// fact folded — the provider backoff behind one model attempt is observable
167/// BEFORE the turn terminates, so a streaming client can render "system words ·
168/// retrying in Ss · attempt N/M" instead of dead air. Non-terminal: it never
169/// resolves a turn-wait. The sibling `turn/retryScheduled` shape at the model
170/// layer: same member names and semantics (attempt/nextAttempt/maxAttempts/
171/// retryDelayMs/system/errorKind/httpStatus), minus `reason` — the row's words
172/// derive from `errorKind` through the shared gate-off mapping, and the
173/// recorded machine message is not user text. The delay is the recorded
174/// scheduled backoff, never an absolute fire time — clients derive any
175/// countdown locally. `sourceRange` cites the session stream's mirror of the
176/// task-lifecycle record.
177#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
178#[serde(rename_all = "camelCase")]
179#[non_exhaustive]
180pub struct TurnModelRetryScheduledParams {
181    /// The owning session.
182    pub session_id: String,
183    /// Opaque, strictly monotonic view cursor.
184    pub view_cursor: String,
185    /// The durable record this event folded from (the session stream's
186    /// mirror of the scheduled model task status; `first == last`).
187    pub source_range: SourceRange,
188    /// The running turn whose model attempt is being retried.
189    pub turn_id: String,
190    /// The failed model attempt (producer-normalized, >= 1).
191    pub attempt: u32,
192    /// The scheduled model attempt (producer contract: attempt <
193    /// nextAttempt <= maxAttempts; not a schema constraint).
194    pub next_attempt: u32,
195    /// The model-retry chain bound.
196    pub max_attempts: u32,
197    /// The scheduled backoff delay in milliseconds, verbatim from the
198    /// durable fact.
199    pub retry_delay_ms: u64,
200    /// The failing model attempt's provider system, verbatim — e.g. `"meta"`.
201    /// Always present from this producer (the durable `system` is a required
202    /// `String`); optional on the wire so a future omission folds absent
203    /// instead of failing the frame.
204    #[serde(skip_serializing_if = "Option::is_none")]
205    pub system: Option<String>,
206    /// The failing model attempt's durable kind, verbatim — a plain string: the
207    /// durable vocabulary is open-ended.
208    #[serde(skip_serializing_if = "Option::is_none")]
209    pub error_kind: Option<String>,
210    /// The failing model attempt's HTTP status.
211    #[serde(skip_serializing_if = "Option::is_none")]
212    pub http_status: Option<u16>,
213}
214
215/// `turn/unqueued` params: a queued submit's reclaim durably won; its
216/// pre-minted turn never runs. Carries the reclaimed `turnId` and the
217/// `commandId` of the `turn/start` that queued it, so a client can restore the
218/// submission's text exactly as for `turn/retracted`. No
219/// `turn/started`/`turn/completed` is ever emitted for this `turnId`.
220/// `sourceRange` cites the SESSION stream's reclaim record — a reclaimed turn
221/// never had a run stream.
222#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
223#[serde(rename_all = "camelCase")]
224#[non_exhaustive]
225pub struct TurnUnqueuedParams {
226    /// The owning session.
227    pub session_id: String,
228    /// Opaque, strictly monotonic view cursor.
229    pub view_cursor: String,
230    /// The durable records this event folded from (the session stream's
231    /// reclaim record).
232    pub source_range: SourceRange,
233    /// The reclaimed turn: pre-minted at admission, never launched.
234    pub turn_id: String,
235    /// The `commandId` of the `turn/start` that queued the reclaimed turn.
236    pub command_id: String,
237}
238
239/// `turn/foregroundCompleted` params: the turn's foreground work is done and
240/// named background reminder checks hold the turn open. Explicitly
241/// non-terminal: the turn ends only at `turn/completed` / `turn/unqueued`.
242#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
243#[serde(rename_all = "camelCase")]
244#[non_exhaustive]
245pub struct TurnForegroundCompletedParams {
246    /// The owning session.
247    pub session_id: String,
248    /// Opaque, strictly monotonic view cursor.
249    pub view_cursor: String,
250    /// The durable records this event folded from, anchored at the first
251    /// blocking link of the firing window.
252    pub source_range: SourceRange,
253    /// The turn whose foreground completed.
254    pub turn_id: String,
255    /// `reminderAgentId`s of the firing's blocking set, never empty; agent
256    /// ids, never display names. Live-best-effort: reads, resume, and
257    /// replay may narrow it to the linked subset.
258    pub blocking_agents: Vec<String>,
259}
260
261/// Turn terminal vocabulary: exactly the runtime's `RunTerminalKind` — closed
262/// in the runtime, wire-open for evolution.
263#[derive(Debug, Clone, PartialEq, Eq)]
264#[non_exhaustive]
265pub enum TurnTerminal {
266    /// The run finished normally.
267    Completed,
268    /// The run ended in a run-fatal error; `error` is present.
269    Failed,
270    /// The terminal for the interrupt, cancel, and host-shutdown lanes.
271    Cancelled,
272    /// A value from a newer host, kept verbatim so an older client decodes the
273    /// rest of the message. Excluded from the generated schema while the enum
274    /// stays declared open; never construct it with a known word.
275    Unknown(String),
276}
277
278/// The settled turn-failure object: `{kind, message, retryable}`.
279#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
280#[serde(rename_all = "camelCase")]
281#[non_exhaustive]
282pub struct TurnError {
283    /// The failure class (open camelCase enum grounded in the runtime's
284    /// terminal failure classification).
285    pub kind: TurnErrorKind,
286    /// Human-readable failure text.
287    pub message: String,
288    /// The server's judgment that resubmitting the same input may succeed.
289    pub retryable: bool,
290    /// Typed quota-exhaustion detail: present iff the stopping failure was the
291    /// quota class. Clients branch on presence, never by parsing `message`.
292    #[serde(skip_serializing_if = "Option::is_none")]
293    pub quota: Option<QuotaDetail>,
294    /// `true` when the provider refused this request. Present only on the live
295    /// `turn/completed`: replayed, snapshot-served and `workflow/resume`
296    /// terminals omit it, so absence does not mean the request was not denied.
297    /// Never `false`.
298    #[serde(default, skip_serializing_if = "std::ops::Not::not")]
299    pub request_denied: bool,
300}
301
302/// Typed quota-exhaustion detail: the limit kind plus the provider's reset
303/// instant.
304#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
305#[serde(rename_all = "camelCase")]
306#[non_exhaustive]
307pub struct QuotaDetail {
308    /// Which quota was exhausted (open enum; unknown values fall back).
309    pub limit_kind: LimitKind,
310    /// Epoch milliseconds at which the provider says usage resets.
311    pub resets_at_ms: i64,
312}
313
314/// Quota limit kinds: open for evolution.
315#[derive(Debug, Clone, PartialEq, Eq)]
316#[non_exhaustive]
317pub enum LimitKind {
318    /// Provider tier quota exhausted (durable `tier_limit`).
319    TierLimit,
320    /// A value from a newer host, kept verbatim so an older client decodes the
321    /// rest of the message. Never construct it with a known word.
322    Unknown(String),
323}
324
325/// Turn failure classes. Open.
326#[derive(Debug, Clone, PartialEq, Eq)]
327#[non_exhaustive]
328pub enum TurnErrorKind {
329    /// The run hit its step limit.
330    StepLimit,
331    /// Configuration failure.
332    ConfigError,
333    /// Projection failure.
334    ProjectionError,
335    /// Event-log failure.
336    LogError,
337    /// Workflow launch failure.
338    WorkflowLaunchError,
339    /// Environment failure.
340    EnvironmentError,
341    /// Model/provider failure.
342    ModelError,
343    /// A deferred (queued/replace) launch failed at the terminal boundary;
344    /// retryable.
345    LaunchError,
346    /// The host has no usable credential, or the provider rejected the
347    /// credential as expired/unauthorized. A plain stable additive open-enum
348    /// value — never experimental-annotated: strip-arming would remove the
349    /// required member.
350    AuthRequired,
351    /// The session's MCP first-run link could not be confirmed, so the run
352    /// stopped before contacting the model. A plain stable additive open-enum
353    /// value, like `AuthRequired`.
354    McpLinkError,
355    /// A value from a newer host, kept verbatim so an older client decodes the
356    /// rest of the message. Excluded from the generated schema while the enum
357    /// stays declared open; never construct it with a known word.
358    Unknown(String),
359}
360
361/// `item/started` params: a new item opened on the transcript. `sourceRange` is
362/// absent when the item opens on an ephemeral record (the delta-streamed
363/// kinds); the item's authoritative open is re-stated by its durable-sourced
364/// `item/completed`.
365#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
366#[serde(rename_all = "camelCase")]
367#[non_exhaustive]
368pub struct ItemStartedParams {
369    /// The owning session.
370    pub session_id: String,
371    /// Opaque, strictly monotonic view cursor.
372    pub view_cursor: String,
373    /// The durable records this event folded from; absent on an
374    /// ephemeral-sourced open.
375    #[serde(skip_serializing_if = "Option::is_none")]
376    pub source_range: Option<SourceRange>,
377    /// The full item at revision 1.
378    pub item: Item,
379}
380
381/// `item/updated` params: an open item changed non-terminally in a way deltas
382/// cannot express — the full item re-emitted at a higher revision (apply rule:
383/// replace iff higher).
384#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
385#[serde(rename_all = "camelCase")]
386#[non_exhaustive]
387pub struct ItemUpdatedParams {
388    /// The owning session.
389    pub session_id: String,
390    /// Opaque, strictly monotonic view cursor.
391    pub view_cursor: String,
392    /// The durable records this event folded from.
393    pub source_range: SourceRange,
394    /// The full item at a higher revision.
395    pub item: Item,
396}
397
398/// `item/completed` params: the item reached its terminal state — the
399/// authoritative final object. Always cites a durable `sourceRange`. Clients
400/// MUST accept `item/completed` for an `itemId` they never saw `item/started`
401/// for.
402#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
403#[serde(rename_all = "camelCase")]
404#[non_exhaustive]
405pub struct ItemCompletedParams {
406    /// The owning session.
407    pub session_id: String,
408    /// Opaque, strictly monotonic view cursor.
409    pub view_cursor: String,
410    /// The durable records this event folded from.
411    pub source_range: SourceRange,
412    /// The full item at its terminal revision.
413    pub item: Item,
414}
415
416/// `item/delta` params: a UTF-8-safe streaming append to an open item's field.
417/// Ephemeral-sourced by definition: this params object has **no** `sourceRange`
418/// member at all. Deltas never bump `revision`.
419#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
420#[serde(rename_all = "camelCase")]
421#[non_exhaustive]
422pub struct ItemDeltaParams {
423    /// The owning session.
424    pub session_id: String,
425    /// Opaque, strictly monotonic view cursor.
426    pub view_cursor: String,
427    /// The open item being appended to.
428    pub item_id: String,
429    /// Dotted field path the append targets (`"summary.0"`, `"output"`,...);
430    /// absent means `"text"`.
431    #[serde(skip_serializing_if = "Option::is_none")]
432    pub field: Option<String>,
433    /// The appended text; concatenation of a field path's deltas in cursor
434    /// order equals that field's value on `item/completed` unless the surface
435    /// saturated.
436    pub delta: String,
437}