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;
8use serde::Deserialize;
9use serde::Deserializer;
10use serde::Serialize;
11pub use session_mcp::SessionConfig;
12pub use session_resume::HistoryNoneReason;
13pub use session_resume::LastTurn;
14pub use session_resume::PendingRequestPointer;
15pub use session_resume::SessionHistory;
16
17pub(crate) mod recovery;
18pub(crate) mod session_leave;
19pub(crate) mod session_list;
20pub(crate) mod session_mcp;
21pub(crate) mod session_resume;
22
23/// `session/start` params.
24#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
25#[serde(rename_all = "camelCase")]
26pub struct SessionStartParams {
27    /// The idempotency handle (UUIDv7). Required; the server never mints one.
28    pub command_id: String,
29    /// Recovery choice for this construction; omission keeps legacy behavior.
30    /// Explicit null is invalid.
31    #[serde(
32        default,
33        deserialize_with = "deserialize_non_null_optional",
34        skip_serializing_if = "Option::is_none"
35    )]
36    pub recovery_mode: Option<RecoveryMode>,
37    /// Exact identity for this new root session. When omitted the server mints
38    /// a UUIDv7. This field never selects an existing session: a retained or
39    /// reserved id is rejected `commandRejected` with reason
40    /// `session_id_conflict`.
41    #[serde(skip_serializing_if = "Option::is_none")]
42    pub session_id: Option<String>,
43    /// Absolute path, folded into the first metadata record.
44    #[serde(skip_serializing_if = "Option::is_none")]
45    pub workspace_root: Option<String>,
46    /// The session's initial runtime workspace-root set: ordered absolute
47    /// canonical existing directory paths; the first root is the CWD and plays
48    /// the primary-root role; every root receives the `:workspace_roots` rules;
49    /// extra roots grant no Project Trust. When `workspaceRoot` is also present
50    /// the two must name the same folder, compared on canonical forms, or the
51    /// request is invalid params, and so is explicit `null`. Omitted preserves
52    /// single-root behavior.
53    #[serde(
54        default,
55        deserialize_with = "deserialize_non_null_optional",
56        skip_serializing_if = "Option::is_none"
57    )]
58    pub workspace_roots: Option<Vec<String>>,
59    /// Initial model; server default when omitted.
60    #[serde(skip_serializing_if = "Option::is_none")]
61    pub model_id: Option<String>,
62    /// Initial provider routing; server default when omitted or explicit `null`
63    /// — both spellings select the default.
64    #[serde(skip_serializing_if = "Option::is_none")]
65    pub provider_id: Option<String>,
66    /// The session's starting approval mode; server default when omitted or
67    /// explicit `null` — both spellings select the default. Select, never
68    /// create — the value names a mode the host's configuration already
69    /// defines. This is the only surface that declares a non-interactive run's
70    /// policy.
71    #[serde(skip_serializing_if = "Option::is_none")]
72    pub approval_mode: Option<ApprovalMode>,
73    /// The new session's initial permission profile: a profile id the host
74    /// catalog already admits — the rows `permissionProfile/list` serves
75    /// without `sessionId`. Select, never create. Omitted means today's
76    /// behavior: the host's configured default under native admission,
77    /// unchanged. An id the catalog does not carry, or one it serves
78    /// unavailable, refuses the start `commandRejected` (-32030;
79    /// `permission_profile_unknown` / `permission_profile_unavailable`) before
80    /// any durable byte, and an ephemeral host refuses any id
81    /// (`permission_profile_ephemeral_fixed`). `session/fork` does not admit
82    /// the member; `session/resume` admits it as the launch pick. Explicit
83    /// `null` is invalid params: the set of members that tolerate `null` is
84    /// closed and excludes this one, exactly as it excludes `workspaceRoots`.
85    #[serde(
86        default,
87        deserialize_with = "deserialize_non_null_optional",
88        skip_serializing_if = "Option::is_none"
89    )]
90    pub permission_profile: Option<String>,
91    /// Reserved for per-session overrides owned by a future Configuration
92    /// section. Issue a tracked change admits only its `mcpServers` member.
93    #[serde(
94        default,
95        deserialize_with = "deserialize_non_null_optional",
96        skip_serializing_if = "Option::is_none"
97    )]
98    pub config: Option<SessionConfig>,
99    /// a tracked change: ask for a created worktree or attach an existing one.
100    /// **Experimental** (`session/start.worktree`; unopted callers are refused
101    /// `-32602`). Absent means no worktree — the start proceeds exactly as
102    /// today.
103    #[serde(skip_serializing_if = "Option::is_none")]
104    pub worktree: Option<WorktreeStartRequest>,
105}
106
107pub(crate) fn deserialize_non_null_optional<'de, D, T>(
108    deserializer: D,
109) -> Result<Option<T>, D::Error>
110where
111    D: Deserializer<'de>,
112    T: Deserialize<'de>,
113{
114    T::deserialize(deserializer).map(Some)
115}
116
117pub(crate) fn deserialize_optional_recovery_observation<'de, D>(
118    deserializer: D,
119) -> Result<Option<RecoveryObservation>, D::Error>
120where
121    D: Deserializer<'de>,
122{
123    let value = serde_json::Value::deserialize(deserializer)?;
124    if !value.is_object() {
125        return Ok(None);
126    }
127    Ok(serde_json::from_value(value).ok())
128}
129
130/// `session/start` result.
131#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
132#[serde(rename_all = "camelCase")]
133#[non_exhaustive]
134pub struct SessionStartResult {
135    /// The new session.
136    pub session: Session,
137    /// The session view head after the start fold; the connection is subscribed
138    /// and receives every view event after this cursor. A deduplicated retry
139    /// returns this same result.
140    pub view_cursor: String,
141}
142
143/// `session/fork` params.
144#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
145#[serde(rename_all = "camelCase")]
146pub struct SessionForkParams {
147    /// The idempotency handle (UUIDv7).
148    pub command_id: String,
149    /// The source session.
150    pub session_id: String,
151    /// Copy history through a completed turn, inclusive. Omitted means "all
152    /// completed turns".
153    #[serde(skip_serializing_if = "Option::is_none")]
154    pub cut_point: Option<ForkCutPoint>,
155    /// Skip inline history in the result and page it later — same as
156    /// `session/resume`.
157    #[serde(skip_serializing_if = "Option::is_none")]
158    pub exclude_items: Option<bool>,
159}
160
161/// Where a fork cuts the source history. Turn ids are used instead of counts
162/// because ids stay stable across compaction and concurrent appends while
163/// indices do not.
164#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
165#[serde(rename_all = "camelCase")]
166pub struct ForkCutPoint {
167    /// The last completed turn to copy, inclusive. Naming an in-progress or
168    /// unknown turn fails `forkBoundaryInvalid`.
169    pub last_turn_id: String,
170}
171
172/// `session/fork` result: the `session/resume` envelope for the **new**
173/// session, whose `session.forkedFrom` carries the provenance.
174#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
175#[serde(rename_all = "camelCase")]
176#[non_exhaustive]
177pub struct SessionForkResult {
178    /// The new fork session, carrying `forkedFrom` provenance.
179    pub session: Session,
180    /// The new session's view head.
181    pub view_cursor: String,
182    /// The served history.
183    pub history: SessionHistory,
184    /// The late-joiner pointer set.
185    pub pending_requests: Vec<PendingRequestPointer>,
186}
187
188/// `session/sideChat` params.
189#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
190#[serde(rename_all = "camelCase")]
191pub struct SessionSideChatParams {
192    /// The idempotency handle (UUIDv7).
193    pub command_id: String,
194    /// The source main session.
195    pub session_id: String,
196}
197
198/// `session/sideChat` result: the `session/resume` envelope for the **new**
199/// side session, whose `session.sideFrom` carries the provenance. The side
200/// opens empty.
201#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
202#[serde(rename_all = "camelCase")]
203#[non_exhaustive]
204pub struct SessionSideChatResult {
205    /// The new side session, carrying `sideFrom` provenance.
206    pub session: Session,
207    /// The new side session's view head.
208    pub view_cursor: String,
209    /// The served history.
210    pub history: SessionHistory,
211    /// The late-joiner pointer set.
212    pub pending_requests: Vec<PendingRequestPointer>,
213}
214
215/// `session/read` params: read one stored session **without attaching** — no
216/// writer lease, no load, no subscription, no `SessionResumed` record.
217#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
218#[serde(rename_all = "camelCase")]
219pub struct SessionReadParams {
220    /// The session to read.
221    pub session_id: String,
222    /// Metadata-only unless you ask: `false` carries the folded item history.
223    /// Same name and polarity as `session/resume`/`session/fork`; only the
224    /// default differs — here it is `true`.
225    #[serde(skip_serializing_if = "Option::is_none")]
226    pub exclude_items: Option<bool>,
227}
228
229/// `session/read` result. The `viewCursor` is the fold head at read time — a
230/// point-in-time read, immediately stale if a foreign host is appending.
231#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
232#[serde(rename_all = "camelCase")]
233#[non_exhaustive]
234pub struct SessionReadResult {
235    /// The session as folded point-in-time.
236    pub session: Session,
237    /// Current local construction only; never inferred from retained history.
238    /// Absence establishes neither a choice nor supported recovery.
239    #[serde(
240        default,
241        deserialize_with = "deserialize_optional_recovery_observation",
242        skip_serializing_if = "Option::is_none"
243    )]
244    pub recovery_observation: Option<RecoveryObservation>,
245    /// The fold head at read time.
246    pub view_cursor: String,
247    /// The served history.
248    pub history: SessionHistory,
249    /// The same pointer shape as `session/resume`. Because `session/read` never
250    /// subscribes this is a point-in-time log read only: no requests are
251    /// re-issued after it.
252    pub pending_requests: Vec<PendingRequestPointer>,
253    /// Same member as `session/resume`.
254    #[serde(default, skip_serializing_if = "Option::is_none")]
255    pub last_turn: Option<LastTurn>,
256}