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