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