Skip to main content

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;
4pub use super::session_satellites::AttentionFlag;
5pub use super::session_satellites::EffectiveApprovalModeState;
6pub use super::session_satellites::EffectivePermissionState;
7pub use super::session_satellites::ForkProvenance;
8pub use super::session_satellites::SessionSpawnedBy;
9pub use super::session_satellites::SideProvenance;
10use crate::msp::method::worktree::SessionWorktree;
11use crate::msp::view::state::SessionNameOrigin;
12use serde::Deserialize;
13use serde::Serialize;
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. Excluded from the generated schema while the enum
31    /// stays declared open; never construct it with a known word.
32    Unknown(String),
33}
34
35/// The session object every lifecycle method returns or lists.
36///
37/// Additive-optional evolution applies: clients must ignore unknown fields.
38#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
39#[serde(rename_all = "camelCase")]
40#[non_exhaustive]
41pub struct Session {
42    /// The session identity.
43    pub session_id: String,
44    /// Absolute path of the session's durable log; non-nullable. Under the
45    /// ephemeral session profile it is the **empty string**, meaning "no
46    /// durable log exists" — the one value a client must not hand to a
47    /// filesystem call.
48    pub path: String,
49    /// Load state as this host knows it; `session/list` reports `notLoaded` for
50    /// sessions loaded by *other* hosts.
51    pub status: SessionStatus,
52    /// The `turnId` of the current foreground turn when `status` is `running`,
53    /// and `null` when the session is idle.
54    ///
55    /// **Required-nullable.** Every served `Session` carries the member: `null`
56    /// when the session is idle or not loaded, the turn id when it is running.
57    /// An optional-absent shape would publish it as plain `string` and reject
58    /// every idle `Session` frame the host sends.
59    pub active_turn_id: Option<String>,
60    /// RFC3339. For a fork this is the fork session id's UUIDv7 mint instant.
61    pub created_at: String,
62    /// RFC3339; never precedes `createdAt`.
63    pub updated_at: String,
64    /// The winning metadata fold's workspace root; `null` when that record
65    /// omits it — absent is never fabricated.
66    pub workspace_root: Option<String>,
67    /// The winning metadata fold's provider; `null` when that record omits it.
68    pub provider_id: Option<String>,
69    /// The winning metadata fold's model; `null` when that record omits it.
70    pub model_id: Option<String>,
71    /// The folded effective approval mode. **Additive-optional**: a Session
72    /// object that omits it means the host has not folded a mode, which is why
73    /// the index-derived `session/list` entry may legitimately omit it.
74    #[serde(skip_serializing_if = "Option::is_none")]
75    pub approval_mode: Option<EffectiveApprovalModeState>,
76    /// The folded effective permission state. **Additive-optional**: a
77    /// `"notLoaded"` row omits it (no live evidence, matching the `attention`
78    /// precedent) and an older host omits it everywhere; absent is unknown,
79    /// never active. `approvalMode` stays the effective-mode answer; this never
80    /// restates it.
81    #[serde(skip_serializing_if = "Option::is_none")]
82    pub permission_state: Option<EffectivePermissionState>,
83    /// Attention flags. **Additive-optional**, present only when at least one
84    /// flag is set; absence is a NON-assertion (nothing pending, or the loaded
85    /// session's pending source declined to answer). Loaded sessions only: a
86    /// `notLoaded` row omits it even while its durable pending set is
87    /// non-empty.
88    #[serde(skip_serializing_if = "Option::is_none")]
89    pub attention: Option<Vec<AttentionFlag>>,
90    /// Content-activity recency, RFC3339. **Additive-optional**: omitted when
91    /// no content record exists. Never advanced by lifecycle bookkeeping (the
92    /// resume marker, re-stamps) or a fork's copied seed-replay records, and
93    /// never precedes `createdAt`.
94    #[serde(skip_serializing_if = "Option::is_none")]
95    pub last_activity_at: Option<String>,
96    /// Completed-turn count from the session view fold.
97    pub turn_count: u64,
98    /// `null` for root sessions; fork provenance otherwise.
99    pub forked_from: Option<ForkProvenance>,
100    /// `null` for root sessions and forks; side provenance otherwise. A session
101    /// carries at most one of `forkedFrom` and `sideFrom`.
102    pub side_from: Option<SideProvenance>,
103    /// The durable allocated session name. **Additive-optional**: present when
104    /// the serving path holds an allocated name, omitted otherwise — absent is
105    /// never fabricated. Authoritative and renameable via `session/rename`.
106    #[serde(skip_serializing_if = "Option::is_none")]
107    pub name: Option<String>,
108    /// How the served `name` was set. **Additive-optional**, **fold-only**: the
109    /// snapshot fold (`session/read`, the resume/start/fork-ack snapshot)
110    /// derives and carries it from the log; `session/list` rows never carry it.
111    /// Absent — and any value the client does not recognize — reads as unknown,
112    /// never fabricated.
113    #[serde(skip_serializing_if = "Option::is_none")]
114    pub name_origin: Option<SessionNameOrigin>,
115    /// The served generated short title. **Additive-optional**, **fold-only**:
116    /// the snapshot fold derives the latest retained generated pair's short
117    /// title from the log; `session/list` rows never carry it. Omitted when no
118    /// pair was ever published — absent reads as unpublished, never fabricated,
119    /// never inferred from the name text. `name` stays the canonical name it
120    /// always was.
121    #[serde(skip_serializing_if = "Option::is_none")]
122    pub generated_name: Option<String>,
123    /// Derived display title: a heuristic that may evolve — its carriage, not
124    /// its derivation, is the contract. **Additive-optional**, omitted when
125    /// underivable.
126    #[serde(skip_serializing_if = "Option::is_none")]
127    pub title: Option<String>,
128    /// Derived first-user-prompt preview. **Additive-optional**, omitted when
129    /// underivable.
130    #[serde(skip_serializing_if = "Option::is_none")]
131    pub first_user_prompt: Option<String>,
132    /// Derived workspace branch — the index's last derived value; the
133    /// live-change signal stays `session/branchChanged`. **Additive-optional**,
134    /// omitted when underivable.
135    #[serde(skip_serializing_if = "Option::is_none")]
136    pub branch: Option<String>,
137    /// What kind of session this is. **Open enum**, v1 values `"root"` and
138    /// `"subagent"`; a client treats an unknown value as an unknown-but-present
139    /// kind and renders it, never rejecting the row. **Additive-optional**:
140    /// absence asserts nothing — the host could not determine the home shape,
141    /// or the value is not yet available to serve.
142    #[serde(skip_serializing_if = "Option::is_none")]
143    pub kind: Option<SessionKind>,
144    /// The containing session's id when `kind` is `"subagent"` — the id of the
145    /// TOP-LEVEL session whose home holds this child, which is **not
146    /// necessarily the session that spawned it**: native-child homes are
147    /// physical siblings under the outer session's `subagent/` directory, so a
148    /// subagent spawned by another subagent resolves to the outer session, not
149    /// to its spawner. A client building a tree from this field gets one level,
150    /// not a chain. Flat rather than nested: there is exactly one fact to
151    /// carry, unlike `forkedFrom`'s four-field `ForkProvenance`.
152    /// **Additive-optional**; a root carries none.
153    #[serde(skip_serializing_if = "Option::is_none")]
154    pub parent_session_id: Option<String>,
155    /// The handshake `ClientInfo` recorded when the session was opened, echoed
156    /// verbatim — provenance, never an interpretation, and never a visibility
157    /// gate. **Additive-optional**; absence has four indistinguishable causes:
158    /// an in-process open; an earlier record; a half stamp where only one of
159    /// name/version was recorded and `ClientInfo` requires both; and a session
160    /// with no admitting handshake of its own — a fork child or a subagent —
161    /// which never carries a stamp to begin with.
162    #[serde(skip_serializing_if = "Option::is_none")]
163    pub created_by_client: Option<crate::msp::handshake::ClientInfo>,
164    /// The handshake `ClientInfo` of the connection whose wire `session/resume`
165    /// most recently loaded this session: stamped on the durable
166    /// `session.resumed` marker, folded into the session index, and served from
167    /// that column by every carrier; while the session is loaded, the stamp the
168    /// loading resume wrote replaces the column on every carrier (the ack,
169    /// `session/read`, `session/list`, `session/listChanged`), and after the
170    /// next fold the column serves it. **Additive-optional** and **provenance
171    /// only**; a resume with no admitting handshake (TUI, exec) stamps nothing,
172    /// a warm attach to an already-loaded session writes no marker, and a half
173    /// stamp serves nothing, so absence asserts nothing. `createdByClient`
174    /// never follows a resume.
175    #[serde(skip_serializing_if = "Option::is_none")]
176    pub resumed_by_client: Option<crate::msp::handshake::ClientInfo>,
177    /// The session that opened this one, recorded once in this session's
178    /// creation record and served from the session index. Its `parentSessionId`
179    /// is the exact spawner, unlike the containing session `parentSessionId`
180    /// names above; `project` and `thread` are opaque labels the spawner may
181    /// name beside it. **Additive-optional** and **provenance only**: never a
182    /// visibility or authority gate. Absence asserts nothing — no recorded
183    /// spawner, a later session of the spawned process, a row folded before the
184    /// member existed, or a session the index has not folded yet.
185    #[serde(skip_serializing_if = "Option::is_none")]
186    pub spawned_by: Option<SessionSpawnedBy>,
187    /// The handshake `ClientInfo` of the connection that currently holds this
188    /// session's drive grant, served on `session/read` only, as `name` and
189    /// `version` (the handshake's display `title` is never served, the
190    /// `createdByClient` rule). **Additive-optional, loaded-only, live**:
191    /// present exactly when a live connection holds the grant and its handshake
192    /// is known; absent on `notLoaded` rows, once the holder's connection drops
193    /// (its orphaned turn included), and for a holder with no handshake stamp.
194    /// Provenance only: whether a client may drive is answered by
195    /// `session/resume` / `turn/start` (`sessionInUse`), never by this member.
196    #[serde(skip_serializing_if = "Option::is_none")]
197    pub drive_holder: Option<crate::msp::handshake::ClientInfo>,
198    /// The worktree this session runs in — path and origin only (the branch
199    /// stays in `branch`). **Experimental** (`Session.worktree`; stripped
200    /// per-connection for unopted callers). Omitted when the session runs in no
201    /// worktree.
202    #[serde(skip_serializing_if = "Option::is_none")]
203    pub worktree: Option<SessionWorktree>,
204    /// This session's effective limits: the clamp output — the sandbox axes
205    /// read the live ceiling, the trust axis clamps the session's durable
206    /// stored choice (the clamp input) to it. `workspaceTrusted` is the trust
207    /// the session runs with. **Experimental, same-user socket only**
208    /// (`Session.currentLimits`; stripped per-connection for unopted callers).
209    /// Loaded sessions only (`notLoaded` rows and hosts with no limits regime
210    /// omit it) — absent is never fabricated.
211    #[serde(skip_serializing_if = "Option::is_none")]
212    pub current_limits: Option<super::limits::SessionLimits>,
213    /// That another live process on this machine runs this session, and which
214    /// kind of process when the host can tell. **Experimental**
215    /// (`Session.runningElsewhere`; stripped per-connection for unopted
216    /// callers), on `session/list` rows and the `session/listChanged` frames
217    /// built from the same row. No frame is pushed when only this member
218    /// changes; a client sees the change on its next `session/list` or on a
219    /// frame sent for another reason. Present exactly when the answering host
220    /// does not hold the session loaded and another live process on this
221    /// machine does (it holds the session's writer lease, or a live local
222    /// session registry record names the session), so only `notLoaded` rows
223    /// carry it. Absence asserts only that the host saw no other holder when it
224    /// built the row. Provenance only: whether a client may drive is answered
225    /// by `session/resume` / `turn/start` (`sessionInUse`), never by this
226    /// member.
227    #[serde(skip_serializing_if = "Option::is_none")]
228    pub running_elsewhere: Option<RunningElsewhere>,
229    /// The published head's ordinal (kt-dvw5): the head reference's own
230    /// ordinal — the count of head slots in its sequence, including any
231    /// reserved ones — as of the probe that served this row. A sizing
232    /// hint for a first `view/page`, so the Console can size its page
233    /// without folding the log. **Additive-optional**, present only on
234    /// metadata reads (`session/read` with `excludeItems`), where the
235    /// client has no items to count; full reads carry the items
236    /// themselves and omit it. Absent when no head is published (unknown),
237    /// never fabricated. May lag a live log: the head is a snapshot, and
238    /// appends after its publication are not counted.
239    #[serde(skip_serializing_if = "Option::is_none")]
240    pub item_count: Option<u64>,
241    /// The durable log's byte length at read time (kt-dvw5): the size hint
242    /// paired with `itemCount`, so the Console can size its first page
243    /// without folding the log. **Additive-optional**, present only on
244    /// metadata reads (`session/read` with `excludeItems`); full reads omit
245    /// it. Absent when the log's length is not known (unknown), never
246    /// fabricated. A live log grows after the read; the value is a snapshot.
247    #[serde(skip_serializing_if = "Option::is_none")]
248    pub log_bytes: Option<u64>,
249}
250
251/// The `runningElsewhere` member of a `Session`: another live process on this
252/// machine runs the session.
253#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
254#[serde(rename_all = "camelCase")]
255#[non_exhaustive]
256pub struct RunningElsewhere {
257    /// Which kind of process runs it, taken only from facts the host already
258    /// reads; omitted when unknown, never guessed.
259    #[serde(skip_serializing_if = "Option::is_none")]
260    pub origin: Option<RunningElsewhereOrigin>,
261}
262
263/// Which kind of process runs a session elsewhere on this machine.
264///
265/// **Open**: a new origin is additive evolution, and a client MUST treat an
266/// unknown value as an unknown-but-present origin rather than rejecting the
267/// row.
268#[derive(Debug, Clone, PartialEq, Eq)]
269#[non_exhaustive]
270pub enum RunningElsewhereOrigin {
271    /// A TUI runs it.
272    Tui,
273    /// `muse exec` runs it.
274    Exec,
275    /// Another `muse serve` host runs it.
276    Serve,
277    /// A value from a newer host, kept verbatim so an older client decodes the
278    /// rest of the message. Excluded from the generated schema while the enum
279    /// stays declared open; never construct it with a known word.
280    Unknown(String),
281}