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