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}