muse_code_sdk/msp/method/lifecycle/session_resume.rs
1// @generated from the MSP stable schema and protocol sources; do not edit by hand.
2
3use super::session_mcp::SessionConfig;
4use crate::msp::method::session::Session;
5use crate::msp::method::snapshot::ViewSnapshot;
6use crate::msp::view::event::TurnError;
7use crate::msp::view::event::TurnTerminal;
8use crate::msp::view::item::Item;
9use serde::Deserialize;
10use serde::Serialize;
11
12mod catch_all;
13
14/// `session/resume` params.
15#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
16#[serde(rename_all = "camelCase")]
17pub struct SessionResumeParams {
18 /// The idempotency handle (UUIDv7). A resume that loads a session writes a
19 /// durable `SessionResumed` record.
20 pub command_id: String,
21 /// Cold-resume replacement choice; omission preserves the retained choice.
22 /// A warm attach rejects a different or unestablished choice as invalidParams.
23 /// Explicit null is invalid.
24 #[serde(
25 default,
26 deserialize_with = "super::deserialize_non_null_optional",
27 skip_serializing_if = "Option::is_none"
28 )]
29 pub recovery_mode: Option<super::RecoveryMode>,
30 /// The session to load.
31 pub session_id: String,
32 /// A view cursor previously observed by this client — or an observed
33 /// `summarizedThrough` compaction anchor. When present the server returns
34 /// only the suffix and `history.mode` is `none`. Omitted and explicit
35 /// `null` both mean "no cursor".
36 #[serde(skip_serializing_if = "Option::is_none")]
37 pub cursor: Option<String>,
38 /// Return only session metadata and live resume state; page history
39 /// separately with `view/page`. Default `false`.
40 #[serde(skip_serializing_if = "Option::is_none")]
41 pub exclude_items: Option<bool>,
42 /// History mode preference, default `auto`. A PREFERENCE, not a budget
43 /// override: when the requested mode does not fit the history budget the
44 /// server downgrades it and `history.mode` reports what was actually
45 /// served. Ignored when `cursor` or `excludeItems` makes it moot.
46 #[serde(skip_serializing_if = "Option::is_none")]
47 pub history: Option<HistoryPreference>,
48 /// The launch permission-profile pick: a profile id the host catalog
49 /// already admits. Select, never create. Omitted means today's behavior:
50 /// restore retained authority only, no override. The host restores first,
51 /// then applies the pick in the same pre-marker step; a pick that fails
52 /// admission refuses the resume `commandRejected` (-32030;
53 /// `permission_profile_unknown` / `permission_profile_unavailable`) before
54 /// any durable byte. Explicit `null` is invalid params (the same closed
55 /// null-tolerant set as at start).
56 #[serde(
57 default,
58 deserialize_with = "super::deserialize_non_null_optional",
59 skip_serializing_if = "Option::is_none"
60 )]
61 pub permission_profile: Option<String>,
62 /// The same open construction-time extension object as `session/start`.
63 #[serde(
64 default,
65 deserialize_with = "super::deserialize_non_null_optional",
66 skip_serializing_if = "Option::is_none"
67 )]
68 pub config: Option<SessionConfig>,
69}
70
71/// The `history` request preference of `session/resume`. The forced values
72/// downgrade `anchored` → `inline` → `snapshot` → `none`; under `auto` the full
73/// rung order is anchoredSnapshot → inline → snapshot → elided snapshot → none.
74#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
75#[serde(rename_all = "camelCase")]
76pub enum HistoryPreference {
77 /// Serve the best rung that fits, anchored first.
78 Auto,
79 /// Prefer the full folded item array.
80 Inline,
81 /// Prefer a folded view state plus suffix.
82 Snapshot,
83 /// Prefer a snapshot anchored at the latest installed compaction boundary.
84 Anchored,
85}
86
87/// The `history` envelope shared by `session/resume`, `session/fork`, and
88/// `session/read`.
89#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
90#[serde(rename_all = "camelCase")]
91#[non_exhaustive]
92pub struct SessionHistory {
93 /// What was actually served — never what was asked for.
94 pub mode: HistoryMode,
95 /// The full folded item array when `mode` is `inline`; `null` otherwise.
96 pub items: Option<Vec<Item>>,
97 /// The folded view state when `mode` is `snapshot` or `anchoredSnapshot`;
98 /// `null` otherwise.
99 pub snapshot: Option<ViewSnapshot>,
100 /// Why no history was served — sent exactly when `mode` is `"none"`.
101 #[serde(skip_serializing_if = "Option::is_none")]
102 pub none_reason: Option<HistoryNoneReason>,
103}
104
105/// Why a result served `history.mode: "none"` — the owning spec typed
106/// unavailability. Open on the client side: an absent (older server) or unknown
107/// (newer server) value decodes conservatively as an unknown reason, and
108/// `viewCursor` text never substitutes for it.
109#[derive(Debug, Clone, PartialEq, Eq)]
110#[non_exhaustive]
111pub enum HistoryNoneReason {
112 /// The request's effective `excludeItems` was `true` (the
113 /// `session/read` default; explicit on resume/fork).
114 Excluded,
115 /// A retained cursor was supplied; the streamed suffix carries the
116 /// history.
117 CursorSuffix,
118 /// Every rung through the elided snapshot exceeded the history budget;
119 /// page via `view/page` from the result's `viewCursor`.
120 HistoryBudget,
121 /// No trustworthy materialized projection exists; paging cannot recover it.
122 ProjectionUnavailable,
123 /// The projection exists but the aggregate materialized read exceeded
124 /// its bounded read cap; page in bounded chunks.
125 ProjectionReadLimit,
126 /// A value from a newer host, kept verbatim so an older client decodes the
127 /// rest of the message. Never construct it with a known word.
128 Unknown(String),
129}
130
131/// What history a lifecycle result actually served. Open on the client side:
132/// report-what-was-served means a client treats an unknown mode as "page it
133/// yourself".
134#[derive(Debug, Clone, PartialEq, Eq)]
135#[non_exhaustive]
136pub enum HistoryMode {
137 /// `snapshot` holds a folded view state anchored at the latest installed
138 /// compaction boundary; `snapshot.anchor` names it.
139 AnchoredSnapshot,
140 /// `items` is the full folded item array.
141 Inline,
142 /// `snapshot` holds a folded view state at `snapshot.viewCursor`.
143 Snapshot,
144 /// No history was served — page it via `view/page` from the result's
145 /// `viewCursor`.
146 None,
147 /// A value from a newer host, kept verbatim so an older client decodes the
148 /// rest of the message. Never construct it with a known word.
149 Unknown(String),
150}
151
152/// A late-joiner pointer at an unsettled server-initiated request. The full
153/// payloads arrive as re-issued server-to-client requests right after a
154/// `session/resume` response; `session/read` never re-issues them.
155///
156/// **A second instance, RULED: the flat discriminated-object precedent is
157/// accepted for this type too, on the `ApprovalSubject` precedent, with the
158/// serialized JSON unchanged. A strict union node kind may be funded later; if
159/// it is, it must cover both this type and `TurnInputPart`.** the protocol spec
160/// ratifies two kind-discriminated entry shapes (`{kind: "approval",
161/// approvalId, viewCursor}` / `{kind: "userInput", userInputId, viewCursor}`);
162/// this is one flat object with both ids optional, so the published schema
163/// accepts `{"kind":"approval","userInputId":…}` and an entry carrying no id at
164/// all. The v1 model names no object-variant union (the `ApprovalSubject`
165/// precedent, followed for `TurnInputPart`), and this instance differs from
166/// that one in a way the ruling should see: `kind` here is an OPEN enum, where
167/// `TurnInputPart.type` is closed.
168#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
169#[serde(rename_all = "camelCase")]
170#[non_exhaustive]
171pub struct PendingRequestPointer {
172 /// The discriminator; v1 values `approval` and `userInput`.
173 pub kind: PendingRequestKind,
174 /// Present on an `approval` entry.
175 #[serde(skip_serializing_if = "Option::is_none")]
176 pub approval_id: Option<String>,
177 /// Present on a `userInput` entry.
178 #[serde(skip_serializing_if = "Option::is_none")]
179 pub user_input_id: Option<String>,
180 /// The cursor the request opened at.
181 pub view_cursor: String,
182}
183
184/// The `pendingRequests` discriminator. Open enum, v1 values `approval` and
185/// `userInput`.
186#[derive(Debug, Clone, PartialEq, Eq)]
187#[non_exhaustive]
188pub enum PendingRequestKind {
189 /// An unsettled approval.
190 Approval,
191 /// An unsettled user-input prompt.
192 UserInput,
193 /// A value from a newer host, kept verbatim so an older client decodes the
194 /// rest of the message. Never construct it with a known word.
195 Unknown(String),
196}
197
198/// `session/resume` result.
199#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
200#[serde(rename_all = "camelCase")]
201#[non_exhaustive]
202pub struct SessionResumeResult {
203 /// The loaded session.
204 pub session: Session,
205 /// The session view head; the connection is subscribed after it. A
206 /// still-loaded session a prior `view/unsubscribe` detached is RE-ATTACHED
207 /// by this resume: live delivery resumes from this head. Explicit-cursor
208 /// re-attach with `(after, head]` engine replay stays `view/subscribe`.
209 pub view_cursor: String,
210 /// The served history.
211 pub history: SessionHistory,
212 /// The late-joiner pointer set; empty when nothing is pending.
213 pub pending_requests: Vec<PendingRequestPointer>,
214 /// How the last folded turn ended. **Additive-optional**; absence is a
215 /// non-assertion.
216 #[serde(default, skip_serializing_if = "Option::is_none")]
217 pub last_turn: Option<LastTurn>,
218}
219
220/// The last `turn/completed` the session-view fold applied, restated on
221/// `session/resume` and `session/read` so a reopened session can report a
222/// failed last turn.
223#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
224#[serde(rename_all = "camelCase")]
225#[non_exhaustive]
226pub struct LastTurn {
227 /// The turn's id, as on its `turn/completed`; clients deduplicate a live
228 /// `turn/completed` against this member by it.
229 pub turn_id: String,
230 /// The turn's terminal.
231 pub terminal: TurnTerminal,
232 /// Copied when the `turn/completed` carried it; a synthesized host-death
233 /// `failed` terminal carries only this (`crash`, `crash_inferred`, or
234 /// `incomplete`). Free display text: clients never branch on it.
235 #[serde(default, skip_serializing_if = "Option::is_none")]
236 pub reason: Option<String>,
237 /// Copied when the `turn/completed` carried it: runtime `failed` terminals
238 /// do, host-death `failed` terminals do not.
239 #[serde(default, skip_serializing_if = "Option::is_none")]
240 pub error: Option<TurnError>,
241}