muse_code_sdk/msp/method/session.rs
1// @generated from the MSP stable schema and protocol sources; do not edit by hand.
2
3pub use super::session_events::SessionStatus;
4use crate::msp::method::worktree::SessionWorktree;
5use crate::msp::view::state::ApprovalMode;
6use crate::msp::view::state::ApprovalModeSource;
7use crate::msp::view::state::PermissionAxes;
8use crate::msp::view::state::ReviewerAuthority;
9use crate::msp::view::state::SessionNameOrigin;
10use serde::Deserialize;
11use serde::Serialize;
12
13mod catch_all;
14
15/// What kind of session this is.
16///
17/// **Open**: a new kind is additive evolution, and a client MUST render an
18/// unknown value as an unknown-but-present kind rather than rejecting the
19/// row. Both v1 values are terms the tree already uses — the child log
20/// directory is `subagent` and `ItemKind` already carries a `subagent`
21/// variant — so no new vocabulary is minted.
22#[derive(Debug, Clone, PartialEq, Eq)]
23#[non_exhaustive]
24pub enum SessionKind {
25 /// A canonical or legacy root home.
26 Root,
27 /// A child home under `<parent-session-dir>/subagent/<child-id>/`.
28 Subagent,
29 /// A value from a newer host, kept verbatim so an older client decodes the
30 /// rest of the message. Never construct it with a known word.
31 Unknown(String),
32}
33
34/// The session object every lifecycle method returns or lists.
35///
36/// Additive-optional evolution applies: clients must ignore unknown fields.
37#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
38#[serde(rename_all = "camelCase")]
39#[non_exhaustive]
40pub struct Session {
41 /// The session identity.
42 pub session_id: String,
43 /// Absolute path of the session's durable log; non-nullable. Under the
44 /// ephemeral session profile it is the **empty string**, meaning "no
45 /// durable log exists" — the one value a client must not hand to a
46 /// filesystem call.
47 pub path: String,
48 /// Load state as this host knows it; `session/list` reports `notLoaded` for
49 /// sessions loaded by *other* hosts.
50 pub status: SessionStatus,
51 /// The `turnId` of the current foreground turn when `status` is `running`,
52 /// and `null` when the session is idle.
53 ///
54 /// **Required-nullable, per the owner ruling on a tracked change. Both
55 /// production writers hard-code `"activeTurnId": null` and nothing strips
56 /// it, so this is what the binary emits and what the protocol spec example
57 /// spells. The optional-absent shape published it as plain `string` and
58 /// REJECTED every idle `Session` frame the host sent — the defect class
59 /// this PR exists to close.
60 ///
61 /// The original evidence for optional-absent ("every committed transcript
62 /// shows the omission") was wrong: those transcripts are hand-authored
63 /// fixtures, not host recordings. They are corrected in the same change
64 /// under the ruling's `regenerationJustification`.
65 pub active_turn_id: Option<String>,
66 /// RFC3339. For a fork this is the fork session id's UUIDv7 mint instant.
67 pub created_at: String,
68 /// RFC3339; never precedes `createdAt`.
69 pub updated_at: String,
70 /// The winning metadata fold's workspace root; `null` when that record
71 /// omits it — absent is never fabricated.
72 pub workspace_root: Option<String>,
73 /// The winning metadata fold's provider; `null` when that record omits it.
74 pub provider_id: Option<String>,
75 /// The winning metadata fold's model; `null` when that record omits it.
76 pub model_id: Option<String>,
77 /// The folded effective approval mode. **Additive-optional**: a Session
78 /// object that omits it means the host has not folded a mode, which is why
79 /// the index-derived `session/list` entry may legitimately omit it.
80 #[serde(skip_serializing_if = "Option::is_none")]
81 pub approval_mode: Option<EffectiveApprovalModeState>,
82 /// The folded effective permission state. **Additive-optional**: a
83 /// `"notLoaded"` row omits it (no live evidence, matching the `attention`
84 /// precedent) and an older host omits it everywhere; absent is unknown,
85 /// never active. `approvalMode` stays the effective-mode answer; this never
86 /// restates it.
87 #[serde(skip_serializing_if = "Option::is_none")]
88 pub permission_state: Option<EffectivePermissionState>,
89 /// Attention flags. **Additive-optional**, present only when at least one
90 /// flag is set; absence is a NON-assertion (nothing pending, or the loaded
91 /// session's pending source declined to answer). Loaded sessions only: a
92 /// `notLoaded` row omits it even while its durable pending set is
93 /// non-empty.
94 #[serde(skip_serializing_if = "Option::is_none")]
95 pub attention: Option<Vec<AttentionFlag>>,
96 /// Content-activity recency, RFC3339. **Additive-optional**: omitted when
97 /// no content record exists. Never advanced by lifecycle bookkeeping (the
98 /// resume marker, re-stamps) or a fork's copied seed-replay records, and
99 /// never precedes `createdAt`.
100 #[serde(skip_serializing_if = "Option::is_none")]
101 pub last_activity_at: Option<String>,
102 /// Completed-turn count from the session view fold.
103 pub turn_count: u64,
104 /// `null` for root sessions; fork provenance otherwise.
105 pub forked_from: Option<ForkProvenance>,
106 /// `null` for root sessions and forks; side provenance otherwise. A session
107 /// carries at most one of `forkedFrom` and `sideFrom`.
108 pub side_from: Option<SideProvenance>,
109 /// The durable allocated session name. **Additive-optional**: present when
110 /// the serving path holds an allocated name, omitted otherwise — absent is
111 /// never fabricated. Authoritative and renameable via `session/rename`.
112 #[serde(skip_serializing_if = "Option::is_none")]
113 pub name: Option<String>,
114 /// How the served `name` was set. **Additive-optional**, **fold-only**: the
115 /// snapshot fold (`session/read`, the resume/start/fork-ack snapshot)
116 /// derives and carries it from the log; `session/list` rows never carry it.
117 /// Absent — and any value the client does not recognize — reads as unknown,
118 /// never fabricated.
119 #[serde(skip_serializing_if = "Option::is_none")]
120 pub name_origin: Option<SessionNameOrigin>,
121 /// The served generated short title. **Additive-optional**, **fold-only**:
122 /// the snapshot fold derives the latest retained generated pair's short
123 /// title from the log; `session/list` rows never carry it. Omitted when no
124 /// pair was ever published — absent reads as unpublished, never fabricated,
125 /// never inferred from the name text. `name` stays the canonical name it
126 /// always was.
127 #[serde(skip_serializing_if = "Option::is_none")]
128 pub generated_name: Option<String>,
129 /// Derived display title: a heuristic that may evolve — its carriage, not
130 /// its derivation, is the contract. **Additive-optional**, omitted when
131 /// underivable.
132 #[serde(skip_serializing_if = "Option::is_none")]
133 pub title: Option<String>,
134 /// Derived first-user-prompt preview. **Additive-optional**, omitted when
135 /// underivable.
136 #[serde(skip_serializing_if = "Option::is_none")]
137 pub first_user_prompt: Option<String>,
138 /// Derived workspace branch — the index's last derived value; the
139 /// live-change signal stays `session/branchChanged`. **Additive-optional**,
140 /// omitted when underivable.
141 #[serde(skip_serializing_if = "Option::is_none")]
142 pub branch: Option<String>,
143 /// What kind of session this is. **Open enum**, v1 values `"root"` and
144 /// `"subagent"`; a client treats an unknown value as an unknown-but-present
145 /// kind and renders it, never rejecting the row. **Additive-optional**:
146 /// absence asserts nothing — the host could not determine the home shape,
147 /// or the value is not yet available to serve.
148 #[serde(skip_serializing_if = "Option::is_none")]
149 pub kind: Option<SessionKind>,
150 /// The containing session's id when `kind` is `"subagent"` — the id of the
151 /// TOP-LEVEL session whose home holds this child, which is **not
152 /// necessarily the session that spawned it**: native-child homes are
153 /// physical siblings under the outer session's `subagent/` directory, so a
154 /// subagent spawned by another subagent resolves to the outer session, not
155 /// to its spawner. A client building a tree from this field gets one level,
156 /// not a chain. Flat rather than nested: there is exactly one fact to
157 /// carry, unlike `forkedFrom`'s four-field `ForkProvenance`.
158 /// **Additive-optional**; a root carries none.
159 #[serde(skip_serializing_if = "Option::is_none")]
160 pub parent_session_id: Option<String>,
161 /// The handshake `ClientInfo` recorded when the session was opened, echoed
162 /// verbatim — provenance, never an interpretation, and never a visibility
163 /// gate. **Additive-optional**; absence has four indistinguishable causes:
164 /// an in-process open; an earlier record; a half stamp where only one of
165 /// name/version was recorded and `ClientInfo` requires both; and a session
166 /// with no admitting handshake of its own — a fork child or a subagent —
167 /// which never carries a stamp to begin with.
168 #[serde(skip_serializing_if = "Option::is_none")]
169 pub created_by_client: Option<crate::msp::handshake::ClientInfo>,
170 /// a tracked change: the worktree this session runs in — path and origin
171 /// only. **Experimental** (`Session.worktree`; stripped per-connection for
172 /// unopted callers). Omitted when the session runs in no worktree.
173 #[serde(skip_serializing_if = "Option::is_none")]
174 pub worktree: Option<SessionWorktree>,
175}
176
177/// `session/listChanged` params: one changed row of the `session/list` shape —
178/// the full Session object as the answering host's list face serves it at
179/// emission, a replace, never a delta. Emitted only on connections that
180/// negotiated the `sessionListStream` capability at `initialize`; row birth
181/// stays on `session/started`, unload pairs with `session/closed`.
182#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
183#[serde(rename_all = "camelCase")]
184#[non_exhaustive]
185pub struct SessionListChangedParams {
186 /// The served list row for the changed session.
187 pub session: Session,
188}
189
190/// One attention flag: a pending server-initiated request class parked on the
191/// session. Open on the wire — clients MUST ignore unknown values; future
192/// attention kinds are additive.
193#[derive(Debug, Clone, PartialEq, Eq)]
194#[allow(clippy::enum_variant_names)]
195#[non_exhaustive]
196pub enum AttentionFlag {
197 /// At least one approval request is open and unresolved.
198 ApprovalPending,
199 /// At least one user-input request is open.
200 InputPending,
201 /// At least one peer-admission request is open. Experimental: stripped
202 /// per-connection for unopted callers.
203 AdmissionPending,
204 /// A value from a newer host, kept verbatim so an older client decodes the
205 /// rest of the message. Never construct it with a known word.
206 Unknown(String),
207}
208
209/// The effective approval-mode projection: the same object
210/// `session/setApprovalMode` returns as `effectiveMode` and the `Session`
211/// object carries as `approvalMode`.
212#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
213#[serde(rename_all = "camelCase")]
214#[non_exhaustive]
215pub struct EffectiveApprovalModeState {
216 /// The mode in effect.
217 pub mode: ApprovalMode,
218 /// How the mode took effect.
219 pub source: ApprovalModeSource,
220 /// The command that last set it; `null` when no command did.
221 pub last_command_id: Option<String>,
222}
223
224/// The effective permission-state projection: the committed native permission
225/// snapshot (profile identity, reviewer authority) plus the live per-session
226/// runtime's attachment evidence. The same object
227/// `session/setPermissionProfile` returns and the `Session` object carries as
228/// `permissionState`. Served values must be coherent: a read never combines an
229/// old profile with a newer runtime's attachment claim.
230#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
231#[serde(rename_all = "camelCase")]
232#[non_exhaustive]
233pub struct EffectivePermissionState {
234 /// The committed profile id; `null` when the committed source is a launch
235 /// override (`LaunchOverrides` pins `id: None`) — the governing rules
236 /// served-site rule; every catalog row and configured/default commit
237 /// carries a non-null id.
238 pub profile_id: Option<String>,
239 /// The committed profile's reviewer authority.
240 pub reviewer_authority: ReviewerAuthority,
241 /// Whether an executable reviewer is currently installed for this loaded
242 /// session (live runtime evidence).
243 pub reviewer_attached: bool,
244 /// The committed profile's effective four axis values: the resolved
245 /// filesystem, network, approval, and reviewer the YOLO predicate reads.
246 /// Omitted when unknown — an older host, the no-profile state, or the
247 /// commit-receipt fallback arm that reports without a re-inspect — and a
248 /// client MUST fall back to the served id there, never infer equivalence it
249 /// cannot see.
250 #[serde(skip_serializing_if = "Option::is_none")]
251 pub axes: Option<PermissionAxes>,
252}
253
254/// Fork provenance folded from the durable `session.fork.created` record.
255#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
256#[serde(rename_all = "camelCase")]
257#[non_exhaustive]
258pub struct ForkProvenance {
259 /// The source session this fork was cut from.
260 pub session_id: String,
261 /// An **opaque provenance string** preserved verbatim from the durable
262 /// record. Display-only — not one of the cursor families: clients MUST NOT
263 /// parse it and no method accepts it.
264 pub cut_cursor: String,
265 /// Whether the fork named an explicit cut point.
266 pub cut_explicit: bool,
267 /// The `commandId` of the `session/fork` that created it.
268 pub command_id: String,
269}
270
271/// Side provenance folded from the durable side provenance.
272#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
273#[serde(rename_all = "camelCase")]
274#[non_exhaustive]
275pub struct SideProvenance {
276 /// The source main session this side was opened from.
277 pub session_id: String,
278 /// An **opaque provenance string** preserved verbatim from the durable side
279 /// provenance (`source_cut_cursor`). Display-only — not one of the cursor
280 /// families: clients MUST NOT parse it and no method accepts it.
281 pub cut_cursor: String,
282 /// The `commandId` of the `session/sideChat` that created it.
283 pub command_id: String,
284}