Skip to main content

muse_code_sdk/msp/method/
lifecycle.rs

1// @generated from the MSP stable schema and protocol sources; do not edit by hand.
2
3use crate::msp::method::session::Session;
4use crate::msp::method::worktree::WorktreeStartRequest;
5use crate::msp::view::state::ApprovalMode;
6pub use recovery::RecoveryMode;
7pub use recovery::RecoveryObservation;
8pub use runtime_worktree::RuntimeWorktree;
9use serde::Deserialize;
10use serde::Deserializer;
11use serde::Serialize;
12pub use session_mcp::SessionConfig;
13pub use session_resume::BlockedPrompt;
14pub use session_resume::HistoryNoneReason;
15pub use session_resume::LastTurn;
16pub use session_resume::PendingRequestPointer;
17pub use session_resume::SessionHistory;
18
19pub(crate) mod recovery;
20pub(crate) mod runtime_worktree;
21pub(crate) mod runtime_worktree_wire_words;
22pub(crate) mod session_leave;
23pub(crate) mod session_list;
24pub(crate) mod session_mcp;
25pub(crate) mod session_resume;
26pub(crate) mod session_resume_wire_words;
27
28/// `session/start` params.
29#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
30#[serde(rename_all = "camelCase")]
31pub struct SessionStartParams {
32    /// The idempotency handle (UUIDv7). Required; the server never mints one.
33    pub command_id: String,
34    /// Recovery choice for this construction; omission keeps legacy behavior.
35    /// Explicit null is invalid.
36    #[serde(
37        default,
38        deserialize_with = "deserialize_non_null_optional",
39        skip_serializing_if = "Option::is_none"
40    )]
41    pub recovery_mode: Option<RecoveryMode>,
42    /// Exact identity for this new root session. When omitted the server mints
43    /// a UUIDv7. This field never selects an existing session: a retained or
44    /// reserved id is rejected `commandRejected` with reason
45    /// `session_id_conflict`.
46    #[serde(skip_serializing_if = "Option::is_none")]
47    pub session_id: Option<String>,
48    /// Absolute path, folded into the first metadata record.
49    #[serde(skip_serializing_if = "Option::is_none")]
50    pub workspace_root: Option<String>,
51    /// The session's initial runtime workspace-root set: ordered absolute
52    /// canonical existing directory paths; the first root is the CWD and plays
53    /// the primary-root role; every root receives the `:workspace_roots` rules;
54    /// extra roots grant no Project Trust. When `workspaceRoot` is also present
55    /// the two must name the same folder, compared on canonical forms, or the
56    /// request is invalid params, and so is explicit `null`. Omitted preserves
57    /// single-root behavior.
58    #[serde(
59        default,
60        deserialize_with = "deserialize_non_null_optional",
61        skip_serializing_if = "Option::is_none"
62    )]
63    pub workspace_roots: Option<Vec<String>>,
64    /// Initial model; server default when omitted.
65    #[serde(skip_serializing_if = "Option::is_none")]
66    pub model_id: Option<String>,
67    /// Initial provider routing; server default when omitted or explicit `null`
68    /// — both spellings select the default.
69    #[serde(skip_serializing_if = "Option::is_none")]
70    pub provider_id: Option<String>,
71    /// The session's starting approval mode; server default when omitted or
72    /// explicit `null` — both spellings select the default. Select, never
73    /// create — the value names a mode the host's configuration already
74    /// defines. This is the only surface that declares a non-interactive run's
75    /// policy.
76    #[serde(skip_serializing_if = "Option::is_none")]
77    pub approval_mode: Option<ApprovalMode>,
78    /// The new session's initial permission profile: a profile id the host
79    /// catalog already admits — the rows `permissionProfile/list` serves
80    /// without `sessionId`. Select, never create. Omitted means today's
81    /// behavior: the host's configured default under native admission,
82    /// unchanged. An id the catalog does not carry, or one it serves
83    /// unavailable, refuses the start `commandRejected` (-32030;
84    /// `permission_profile_unknown` / `permission_profile_unavailable`) before
85    /// any durable byte, and an ephemeral host refuses any id
86    /// (`permission_profile_ephemeral_fixed`). `session/fork` does not admit
87    /// the member; `session/resume` admits it as the launch pick. Explicit
88    /// `null` is invalid params: the set of members that tolerate `null` is
89    /// closed and excludes this one, exactly as it excludes `workspaceRoots`.
90    #[serde(
91        default,
92        deserialize_with = "deserialize_non_null_optional",
93        skip_serializing_if = "Option::is_none"
94    )]
95    pub permission_profile: Option<String>,
96    /// Reserved for future per-session overrides; only its `mcpServers` member
97    /// is admitted.
98    #[serde(
99        default,
100        deserialize_with = "deserialize_non_null_optional",
101        skip_serializing_if = "Option::is_none"
102    )]
103    pub config: Option<SessionConfig>,
104    /// The session that opens this one, in the `Session.spawnedBy` shape: a
105    /// spawner that starts a worker session over MSP names its own session
106    /// here. The host writes it once into the new session's creation record, as
107    /// a worker process records its environment hand-over, and `session/list` /
108    /// `session/read` serve it back as `Session.spawnedBy`; `session/resume`
109    /// never takes it. **Additive-optional** and **provenance only**. A value
110    /// the host cannot use (a `parentSessionId` that is not a session id, a
111    /// malformed member) records nothing and never refuses the start; an
112    /// unusable `project` or `thread` is dropped on its own. Hosts that predate
113    /// the member ignore it.
114    #[serde(skip_serializing_if = "Option::is_none")]
115    pub spawned_by: Option<super::session::SessionSpawnedBy>,
116    /// Ask for a created worktree or attach an existing one. **Experimental**
117    /// (`session/start.worktree`; unopted callers are refused `-32602`). Absent
118    /// means no worktree — the start proceeds exactly as today.
119    #[serde(skip_serializing_if = "Option::is_none")]
120    pub worktree: Option<WorktreeStartRequest>,
121    /// The per-session restriction: the axes this session chooses, each at or
122    /// below the host ceiling. **Experimental, socket-only**
123    /// (`session/start.limits`; unopted callers are refused `-32602`, as are
124    /// opted callers on hosts with no limits regime). Absent means the default
125    /// on every axis — the daemon default for trust, the ceiling for the
126    /// sandbox axes. A choice wider than the ceiling on any axis refuses the
127    /// start `-32028 limitsAboveMax` naming every too-wide axis.
128    #[serde(skip_serializing_if = "Option::is_none")]
129    pub limits: Option<super::limits::SessionLimitsChoice>,
130    /// The `/new` predecessor link: the outgoing session this start succeeds.
131    /// Any syntactically valid session UUID; there is no existence check, so a
132    /// link to a session that is gone still commits. Omitted means a true root.
133    /// Explicit `null` is invalid params.
134    #[serde(
135        default,
136        deserialize_with = "deserialize_non_null_optional",
137        skip_serializing_if = "Option::is_none"
138    )]
139    pub previous_session_id: Option<String>,
140}
141
142pub(crate) fn deserialize_non_null_optional<'de, D, T>(
143    deserializer: D,
144) -> Result<Option<T>, D::Error>
145where
146    D: Deserializer<'de>,
147    T: Deserialize<'de>,
148{
149    T::deserialize(deserializer).map(Some)
150}
151
152pub(crate) fn deserialize_optional_recovery_observation<'de, D>(
153    deserializer: D,
154) -> Result<Option<RecoveryObservation>, D::Error>
155where
156    D: Deserializer<'de>,
157{
158    let value = serde_json::Value::deserialize(deserializer)?;
159    if !value.is_object() {
160        return Ok(None);
161    }
162    Ok(serde_json::from_value(value).ok())
163}
164
165/// `session/start` result.
166#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
167#[serde(rename_all = "camelCase")]
168#[non_exhaustive]
169pub struct SessionStartResult {
170    /// The new session.
171    pub session: Session,
172    /// The session view head after the start fold; the connection is subscribed
173    /// and receives every view event after this cursor. A deduplicated retry
174    /// returns this same result.
175    pub view_cursor: String,
176}
177
178/// `session/fork` params.
179#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
180#[serde(rename_all = "camelCase")]
181pub struct SessionForkParams {
182    /// The idempotency handle (UUIDv7).
183    pub command_id: String,
184    /// The source session.
185    pub session_id: String,
186    /// Copy history through a completed turn, inclusive. Omitted means "all
187    /// completed turns".
188    #[serde(skip_serializing_if = "Option::is_none")]
189    pub cut_point: Option<ForkCutPoint>,
190    /// Skip inline history in the result and page it later — same as
191    /// `session/resume`.
192    #[serde(skip_serializing_if = "Option::is_none")]
193    pub exclude_items: Option<bool>,
194}
195
196/// Where a fork cuts the source history. Turn ids are used instead of counts
197/// because ids stay stable across compaction and concurrent appends while
198/// indices do not.
199#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
200#[serde(rename_all = "camelCase")]
201pub struct ForkCutPoint {
202    /// The last completed turn to copy, inclusive. Naming an in-progress or
203    /// unknown turn fails `forkBoundaryInvalid`.
204    pub last_turn_id: String,
205}
206
207/// `session/fork` result: the `session/resume` envelope for the **new**
208/// session, whose `session.forkedFrom` carries the provenance.
209#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
210#[serde(rename_all = "camelCase")]
211#[non_exhaustive]
212pub struct SessionForkResult {
213    /// The new fork session, carrying `forkedFrom` provenance.
214    pub session: Session,
215    /// The new session's view head.
216    pub view_cursor: String,
217    /// The served history.
218    pub history: SessionHistory,
219    /// The late-joiner pointer set.
220    pub pending_requests: Vec<PendingRequestPointer>,
221}
222
223/// `session/sideChat` params.
224#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
225#[serde(rename_all = "camelCase")]
226pub struct SessionSideChatParams {
227    /// The idempotency handle (UUIDv7).
228    pub command_id: String,
229    /// The source main session.
230    pub session_id: String,
231}
232
233/// `session/sideChat` result: the `session/resume` envelope for the **new**
234/// side session, whose `session.sideFrom` carries the provenance. The side
235/// opens empty.
236#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
237#[serde(rename_all = "camelCase")]
238#[non_exhaustive]
239pub struct SessionSideChatResult {
240    /// The new side session, carrying `sideFrom` provenance.
241    pub session: Session,
242    /// The new side session's view head.
243    pub view_cursor: String,
244    /// The served history.
245    pub history: SessionHistory,
246    /// The late-joiner pointer set.
247    pub pending_requests: Vec<PendingRequestPointer>,
248}
249
250/// `session/read` params: read one stored session **without attaching** — no
251/// writer lease, no load, no subscription, no `SessionResumed` record.
252#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
253#[serde(rename_all = "camelCase")]
254pub struct SessionReadParams {
255    /// The session to read.
256    pub session_id: String,
257    /// Metadata-only unless you ask: `false` carries the folded item history.
258    /// Same name and polarity as `session/resume`/`session/fork`; only the
259    /// default differs — here it is `true`.
260    #[serde(skip_serializing_if = "Option::is_none")]
261    pub exclude_items: Option<bool>,
262}
263
264/// `session/read` result. The `viewCursor` is the fold head at read time — a
265/// point-in-time read, immediately stale if a foreign host is appending.
266#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
267#[serde(rename_all = "camelCase")]
268#[non_exhaustive]
269pub struct SessionReadResult {
270    /// The session as folded point-in-time.
271    pub session: Session,
272    /// Current local construction only; never inferred from retained history.
273    /// Absence establishes neither a choice nor supported recovery.
274    #[serde(
275        default,
276        deserialize_with = "deserialize_optional_recovery_observation",
277        skip_serializing_if = "Option::is_none"
278    )]
279    pub recovery_observation: Option<RecoveryObservation>,
280    /// The fold head at read time.
281    pub view_cursor: String,
282    /// The served history.
283    pub history: SessionHistory,
284    /// The same pointer shape as `session/resume`. Because `session/read` never
285    /// subscribes this is a point-in-time log read only: no requests are
286    /// re-issued after it.
287    pub pending_requests: Vec<PendingRequestPointer>,
288    /// Same member as `session/resume`.
289    #[serde(default, skip_serializing_if = "Option::is_none")]
290    pub last_turn: Option<LastTurn>,
291    /// Same member as `session/resume`.
292    #[serde(default, skip_serializing_if = "Option::is_none")]
293    pub blocked_prompt: Option<BlockedPrompt>,
294    /// The inputs still queued for delivery to the read session.
295    /// Absent-when-empty: a missing member means nothing queued, never an
296    /// error.
297    #[serde(default, skip_serializing_if = "Option::is_none")]
298    pub queued_inputs: Option<Vec<QueuedInput>>,
299    /// The facts of the runtime-owned worktree a child read session's subagent
300    /// runs in. A root read serves it absent; absent means no worktree facts,
301    /// never an error.
302    #[serde(default, skip_serializing_if = "Option::is_none")]
303    pub worktree: Option<RuntimeWorktree>,
304}
305
306/// One input still queued for delivery to a session: the full message body plus
307/// its log record sequence, the delivery-order and re-read dedupe key, plus the
308/// run-log record id clients join served entries against record-seeded rows by.
309#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
310#[serde(rename_all = "camelCase")]
311#[non_exhaustive]
312pub struct QueuedInput {
313    /// The full message body, verbatim (never truncated, never a summary).
314    pub text: String,
315    /// The queued record's log sequence: delivery order, and the key
316    /// clients deduplicate re-reads by.
317    pub sequence: u64,
318    /// The run-log record id the served mirror was taken from: the key
319    /// clients join served entries against record-seeded rows by, so an
320    /// already-rendered input never mints a second row under diverged
321    /// sequences. Absent when the host's record carries no mirror
322    /// metadata (a pre-feature host), which falls back to sequence-key
323    /// dedup only.
324    #[serde(default, skip_serializing_if = "Option::is_none")]
325    pub source_run_record_id: Option<String>,
326    /// The `SubagentInput` record's model-authored command id: the key
327    /// wire-twin rows join by in either order (the twin reads the same
328    /// string from the verbatim wire args). Absent for root own-queue
329    /// members, which are never `SubagentInput`.
330    #[serde(default, skip_serializing_if = "Option::is_none")]
331    pub source_command_id: Option<String>,
332}