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}