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