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