Skip to main content

muse_code_sdk/msp/method/
session_events.rs

1// @generated from the MSP stable schema and protocol sources; do not edit by hand.
2
3use super::session::AttentionFlag;
4use super::session::EffectivePermissionState;
5use super::session::NeedsInputReason;
6use super::session::Session;
7use serde::Deserialize;
8use serde::Serialize;
9
10/// `session/statusChanged` params: a loaded session's projected `(status,
11/// attention, needsInputReasons)` value flipped. A command-plane broadcast —
12/// delivered to every connection regardless of its view subscription set, never
13/// gated, no `sourceRange`; the same facts live on the Session object, which is
14/// how a client seeds its table (no initial burst on connect).
15#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
16#[serde(rename_all = "camelCase")]
17#[non_exhaustive]
18pub struct SessionStatusChangedParams {
19    /// The owning session.
20    pub session_id: String,
21    /// Load state after the transition.
22    pub status: SessionStatus,
23    /// Attention flags after the transition; present only when at least one
24    /// flag is set.
25    #[serde(skip_serializing_if = "Option::is_none")]
26    pub attention: Option<Vec<AttentionFlag>>,
27    /// Why the session's input is needed after the transition; present only
28    /// when non-empty. `status` is `needsInput` exactly when this set is
29    /// non-empty. **Experimental**.
30    #[serde(skip_serializing_if = "Option::is_none")]
31    pub needs_input_reasons: Option<Vec<NeedsInputReason>>,
32    /// The folded effective permission state — the same object the `Session`
33    /// carries as `permissionState`. **Additive- optional**: a loaded session
34    /// carries it; a `"notLoaded"` unload frame and an older host omit it (the
35    /// `attention` precedent), and absence is unknown, never active. A
36    /// projection of the ONE stored attach face `session/read` and the
37    /// `session/list` rows serve, never a restatement. Part of the change gate:
38    /// a change in ONLY this answer — with `(status, attention,
39    /// needsInputReasons)` unchanged — is a publishable change, deduped only
40    /// when value-identical, carried on the next `session/statusChanged` frame.
41    #[serde(skip_serializing_if = "Option::is_none")]
42    pub permission_state: Option<EffectivePermissionState>,
43    /// The causing record's view cursor. Required-nullable: `null` exactly when
44    /// the paired `session/closed`'s cursor is `null` (the unload fold-failure
45    /// arm); a definite cursor everywhere else.
46    pub view_cursor: Option<String>,
47}
48
49/// A session's load state.
50#[derive(Debug, Clone, PartialEq, Eq)]
51#[non_exhaustive]
52pub enum SessionStatus {
53    /// A durable log exists and no host has it loaded.
54    NotLoaded,
55    /// Loaded, no active run, no input needed.
56    Idle,
57    /// Loaded, a run in flight, no input needed.
58    Running,
59    /// Loaded, the session's input is needed: at least one `needsInputReasons`
60    /// reason is present. Wins over `idle` / `running`, including while a turn
61    /// is parked on the request. **Experimental**: a connection that did not
62    /// opt in receives the `"idle"` fallback for this value.
63    NeedsInput,
64    /// A value from a newer host, kept verbatim so an older client decodes the
65    /// rest of the message. Excluded from the generated schema while the enum
66    /// stays declared open; never construct it with a known word.
67    Unknown(String),
68}
69
70/// `session/started` params: a session became newly loaded on this host via
71/// `session/start`, `session/fork`, or `session/sideChat`, broadcast to every
72/// initialized connection.
73///
74/// The one member is the same `$defs/Session` object the
75/// `session/start`/`session/fork` results carry, so the broadcast and the
76/// result describe one fact through one type — the host builds the broadcast
77/// payload as a `$defs/Session` — the fresh-start arm reuses the result's
78/// `session` member, the start-replay arm builds the live attach snapshot —
79/// and the emission is
80/// parity-gated against this type at the producer
81/// (`session-server` prod-assembly capture) and over the committed
82/// transcript corpus (conformance `session_lifecycle_enrollment`).
83#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
84#[serde(rename_all = "camelCase")]
85#[non_exhaustive]
86pub struct SessionStartedParams {
87    /// The newly loaded session, as of the start/fork fold.
88    pub session: Session,
89}
90
91/// `session/closed` params: a loaded session was unloaded from this host,
92/// broadcast to every initialized connection. After it, the session is
93/// `notLoaded`; the log remains on disk and `session/resume` reloads it. A
94/// crash emits nothing — only the orderly unload paths do (idle unload, host
95/// shutdown and a released `session/leave`), and each writes the durable
96/// `SessionEnd` record first.
97#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
98#[serde(rename_all = "camelCase")]
99#[non_exhaustive]
100pub struct SessionClosedParams {
101    /// The unloaded session.
102    pub session_id: String,
103    /// Which orderly unload path fired.
104    pub reason: SessionClosedReason,
105    /// The final view head; a client that stores it can later `session/resume
106    /// {cursor}` and receive exactly the (empty) suffix. An **opaque** view
107    /// cursor: clients relay it, never parse it.
108    ///
109    /// **Required-nullable**: the producers always write the member and write
110    /// `null` when the final fold failed at unload — the host defines no cursor
111    /// values of its own and never invents one, and the subscriber still learns
112    /// the session closed.
113    pub view_cursor: Option<String>,
114}
115
116/// The closed-reason vocabulary. Server-produced and published OPEN by owner
117/// ruling — the menu-B pick, which settles that this notification reason enum
118/// publishes open rather than resting on the result-vocabulary rule by analogy.
119/// A crash is deliberately not a reason, because a crash emits no notification
120/// at all.
121#[derive(Debug, Clone, PartialEq, Eq)]
122#[non_exhaustive]
123pub enum SessionClosedReason {
124    /// The idle unload policy fired.
125    Idle,
126    /// Orderly daemon or stdio-EOF drain, including the SIGTERM/SIGINT
127    /// wind-down.
128    HostShutdown,
129    /// A `session/leave` released this session after proven physical release.
130    /// Emitted before its paired `session/statusChanged` and the
131    /// `session/leaveCompleted` terminal.
132    Leave,
133    /// A draining daemon unloaded this session on the upgrade path and released
134    /// its lease. The successor on the canonical socket reloads it at the next
135    /// resume. Socket-only, experimental tier. A connection that did not opt in
136    /// receives the `hostShutdown` fallback for this value; opted-in
137    /// connections decode `vacated`.
138    Vacated,
139    /// A value from a newer host, kept verbatim so an older client decodes the
140    /// rest of the message. Excluded from the generated schema while the enum
141    /// stays declared open; never construct it with a known word.
142    Unknown(String),
143}