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 it names an event the server
34 /// still holds, the server returns only the suffix and `history.mode` is
35 /// `none`. A cursor the server minted that names no event yet, such as the
36 /// empty start cursor of a session that had no events, is treated as no
37 /// cursor: the server serves what a resume without a cursor would. A cursor
38 /// older than the earliest event the server still holds gets a snapshot, or
39 /// `-32040` `viewTruncated` when none fits. A cursor this session's view
40 /// never minted is refused with `-32011` `notFound`, reason
41 /// `missingAnchor`, and a compaction anchor naming a boundary the server
42 /// has pruned is refused with `-32042` `boundaryPruned`. Omitted and
43 /// explicit `null` both mean "no cursor".
44 #[serde(skip_serializing_if = "Option::is_none")]
45 pub cursor: Option<String>,
46 /// Return only session metadata and live resume state; page history
47 /// separately with `view/page`. Default `false`.
48 #[serde(skip_serializing_if = "Option::is_none")]
49 pub exclude_items: Option<bool>,
50 /// History mode preference, default `auto`. A PREFERENCE, not a budget
51 /// override: when the requested mode does not fit the history budget the
52 /// server downgrades it and `history.mode` reports what was actually
53 /// served. Ignored when `cursor` or `excludeItems` makes it moot.
54 #[serde(skip_serializing_if = "Option::is_none")]
55 pub history: Option<HistoryPreference>,
56 /// The launch permission-profile pick: a profile id the host catalog
57 /// already admits. Select, never create. Omitted restores retained
58 /// authority only, with no override. The host restores first, then applies
59 /// the pick in the same pre-marker step; over a declared lost record the
60 /// restore is the never-wider reset, committed before the pick, and where
61 /// the reset cannot commit the pick is committed alone as that reset. A
62 /// pick that fails admission refuses the resume `commandRejected` (-32030;
63 /// `permission_profile_unknown` / `permission_profile_unavailable`) before
64 /// any durable byte. Explicit `null` is invalid params (the same closed
65 /// null-tolerant set as at start).
66 #[serde(
67 default,
68 deserialize_with = "super::deserialize_non_null_optional",
69 skip_serializing_if = "Option::is_none"
70 )]
71 pub permission_profile: Option<String>,
72 /// The explicit MSP model override: a model string the caller supplies at
73 /// resume time. When present it wins over the retained binding's recorded
74 /// origin — over a stamped label and over a stamped pin — and it recovers
75 /// an otherwise-unresolved label binding by sending the override as the
76 /// wire model instead of the unresolved refusal. Omitted preserves arm (2):
77 /// the retained binding resolves by recorded origin exactly as without this
78 /// member. Explicit `null` is invalid params (the same closed null-tolerant
79 /// set as at start). The override changes the model within the retained
80 /// provider; it never names a provider, and it never touches the retained
81 /// profile.
82 #[serde(
83 default,
84 deserialize_with = "super::deserialize_non_null_optional",
85 skip_serializing_if = "Option::is_none"
86 )]
87 pub model_id: Option<String>,
88 /// The same open construction-time extension object as `session/start`.
89 #[serde(
90 default,
91 deserialize_with = "super::deserialize_non_null_optional",
92 skip_serializing_if = "Option::is_none"
93 )]
94 pub config: Option<SessionConfig>,
95}
96
97/// The `history` request preference of `session/resume`. The forced values
98/// downgrade `anchored` → `inline` → `snapshot` → `none`; under `auto` the full
99/// rung order is anchoredSnapshot → inline → snapshot → elided snapshot → none.
100#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
101#[serde(rename_all = "camelCase")]
102pub enum HistoryPreference {
103 /// Serve the best rung that fits, anchored first.
104 Auto,
105 /// Prefer the full folded item array.
106 Inline,
107 /// Prefer a folded view state plus suffix.
108 Snapshot,
109 /// Prefer a snapshot anchored at the latest installed compaction boundary.
110 Anchored,
111}
112
113/// The `history` envelope shared by `session/resume`, `session/fork`, and
114/// `session/read`.
115#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
116#[serde(rename_all = "camelCase")]
117#[non_exhaustive]
118pub struct SessionHistory {
119 /// What was actually served — never what was asked for.
120 pub mode: HistoryMode,
121 /// The full folded item array when `mode` is `inline`; `null` otherwise.
122 pub items: Option<Vec<Item>>,
123 /// The folded view state when `mode` is `snapshot` or `anchoredSnapshot`;
124 /// `null` otherwise.
125 pub snapshot: Option<ViewSnapshot>,
126 /// Why no history was served — sent exactly when `mode` is `"none"`.
127 #[serde(skip_serializing_if = "Option::is_none")]
128 pub none_reason: Option<HistoryNoneReason>,
129 /// The checkpoint-prune boundary: rows for served items at-or-before
130 /// `through_item_id` in served order predate the selected checkpoint.
131 /// Additive-optional; absence is a non-assertion.
132 #[serde(default, skip_serializing_if = "Option::is_none")]
133 pub checkpoint_boundary: Option<CheckpointBoundary>,
134}
135
136/// A served checkpoint-prune boundary: `through_item_id` names the last
137/// first-opened item that opened strictly before the boundary checkpoint event.
138#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
139#[serde(rename_all = "camelCase")]
140#[non_exhaustive]
141pub struct CheckpointBoundary {
142 /// The last pre-boundary item's id, in served (first-opened) order.
143 pub through_item_id: String,
144}
145
146/// Why a result served `history.mode: "none"`: the server's typed reason for
147/// serving no history. Open on the client side: an absent (older server) or
148/// unknown (newer server) value decodes conservatively as an unknown reason,
149/// and `viewCursor` text never substitutes for it.
150#[derive(Debug, Clone, PartialEq, Eq)]
151#[non_exhaustive]
152pub enum HistoryNoneReason {
153 /// The request's effective `excludeItems` was `true` (the
154 /// `session/read` default; explicit on resume/fork).
155 Excluded,
156 /// A retained cursor was supplied; the streamed suffix carries the
157 /// history.
158 CursorSuffix,
159 /// Every rung through the elided snapshot exceeded the history budget;
160 /// page via `view/page` from the result's `viewCursor`.
161 HistoryBudget,
162 /// No trustworthy materialized projection exists; paging cannot recover it.
163 ProjectionUnavailable,
164 /// The projection exists but the aggregate materialized read exceeded
165 /// its bounded read cap; page in bounded chunks.
166 ProjectionReadLimit,
167 /// A value from a newer host, kept verbatim so an older client decodes the
168 /// rest of the message. Excluded from the generated schema while the enum
169 /// stays declared open; never construct it with a known word.
170 Unknown(String),
171}
172
173/// What history a lifecycle result actually served. Open on the client side:
174/// report-what-was-served means a client treats an unknown mode as "page it
175/// yourself".
176#[derive(Debug, Clone, PartialEq, Eq)]
177#[non_exhaustive]
178pub enum HistoryMode {
179 /// `snapshot` holds a folded view state anchored at the latest installed
180 /// compaction boundary; `snapshot.anchor` names it.
181 AnchoredSnapshot,
182 /// `items` is the full folded item array.
183 Inline,
184 /// `snapshot` holds a folded view state at `snapshot.viewCursor`.
185 Snapshot,
186 /// No history was served — page it via `view/page` from the result's
187 /// `viewCursor`.
188 None,
189 /// A value from a newer host, kept verbatim so an older client decodes the
190 /// rest of the message. Excluded from the generated schema while the enum
191 /// stays declared open; never construct it with a known word.
192 Unknown(String),
193}
194
195/// A late-joiner pointer at an unsettled server-initiated request. The full
196/// payloads arrive as re-issued server-to-client requests right after a
197/// `session/resume` response; `session/read` never re-issues them.
198///
199/// The protocol defines two kind-discriminated entry shapes (`{kind:
200/// "approval", approvalId, viewCursor}` / `{kind: "userInput", userInputId,
201/// viewCursor}`). This type is one flat object with both ids optional, as for
202/// `ApprovalSubject` and `TurnInputPart`, because the v1 model names no
203/// object-variant union; the serialized JSON is the same, but the published
204/// schema also accepts `{"kind":"approval","userInputId":…}` and an entry
205/// carrying no id at all. Unlike `TurnInputPart.type`, `kind` here is an OPEN
206/// enum.
207#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
208#[serde(rename_all = "camelCase")]
209#[non_exhaustive]
210pub struct PendingRequestPointer {
211 /// The discriminator; v1 values `approval` and `userInput`.
212 pub kind: PendingRequestKind,
213 /// Present on an `approval` entry.
214 #[serde(skip_serializing_if = "Option::is_none")]
215 pub approval_id: Option<String>,
216 /// Present on a `userInput` entry.
217 #[serde(skip_serializing_if = "Option::is_none")]
218 pub user_input_id: Option<String>,
219 /// The cursor the request opened at.
220 pub view_cursor: String,
221}
222
223/// The `pendingRequests` discriminator. Open enum, v1 values `approval` and
224/// `userInput`.
225#[derive(Debug, Clone, PartialEq, Eq)]
226#[non_exhaustive]
227pub enum PendingRequestKind {
228 /// An unsettled approval.
229 Approval,
230 /// An unsettled user-input prompt.
231 UserInput,
232 /// A value from a newer host, kept verbatim so an older client decodes the
233 /// rest of the message. Never construct it with a known word.
234 Unknown(String),
235}
236
237/// `session/resume` result.
238#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
239#[serde(rename_all = "camelCase")]
240#[non_exhaustive]
241pub struct SessionResumeResult {
242 /// The loaded session.
243 pub session: Session,
244 /// The session view head; the connection is subscribed after it. A
245 /// still-loaded session a prior `view/unsubscribe` detached is RE-ATTACHED
246 /// by this resume: live delivery resumes from this head. Explicit-cursor
247 /// re-attach with `(after, head]` engine replay stays `view/subscribe`.
248 pub view_cursor: String,
249 /// The served history.
250 pub history: SessionHistory,
251 /// The late-joiner pointer set; empty when nothing is pending.
252 pub pending_requests: Vec<PendingRequestPointer>,
253 /// How the last folded turn ended. **Additive-optional**; absence is a
254 /// non-assertion.
255 #[serde(default, skip_serializing_if = "Option::is_none")]
256 pub last_turn: Option<LastTurn>,
257 /// The axes this resume tightened: when the stored choice exceeds the
258 /// restarted host's narrower ceiling, the resume clamps to fit, carries the
259 /// tightened `currentLimits` on the session, and names each tightened axis
260 /// here. **Experimental, same-user socket only**
261 /// (`session/resume.tightenedAxes`; stripped per-connection for unopted
262 /// callers). Absent when nothing tightened — never an empty array.
263 #[serde(default, skip_serializing_if = "Option::is_none")]
264 pub tightened_axes: Option<Vec<String>>,
265 /// The recallable blocked prompt's refill text. **Additive-optional**;
266 /// absence means no blocked prompt to recall (an unblocked session, or a
267 /// pre-feature host). Data only, never a rendered row: clients seed cold
268 /// recall from it (C-p refills `text`) and MUST NOT display it as history.
269 #[serde(default, skip_serializing_if = "Option::is_none")]
270 pub blocked_prompt: Option<BlockedPrompt>,
271 /// The previous run's abnormal end this resume's own load adopted.
272 /// **Experimental** (`session/resume.abnormalEnd`; stripped for unopted
273 /// connections); absence asserts nothing (an attach to a loaded session, a
274 /// clean prior end, or an older host). Clients may show a one-time notice
275 /// from it.
276 #[serde(default, skip_serializing_if = "Option::is_none")]
277 pub abnormal_end: Option<AbnormalEnd>,
278}
279
280/// `abnormalEnd` on `session/resume`: the load found the session's latest serve
281/// segment without a clean end and recorded (or had already recorded) the
282/// `crash_inferred` backstop.
283#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
284#[serde(rename_all = "camelCase")]
285#[non_exhaustive]
286pub struct AbnormalEnd {
287 /// RFC 3339 time of the session's latest serve activity (the time the
288 /// gate-off notice shows); absent when the log has none.
289 #[serde(default, skip_serializing_if = "Option::is_none")]
290 pub last_activity_at: Option<String>,
291}
292
293/// The cold recall seed on `session/resume` and `session/read` results: at most
294/// one, the latest blocked Main prompt — exactly the host's mirror of
295/// `prompt_recovery::replay::ReplayInput`'s choice.
296#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
297#[serde(rename_all = "camelCase")]
298#[non_exhaustive]
299pub struct BlockedPrompt {
300 /// The exact submitted prompt, verbatim — no truncation, no
301 /// normalization; recall fidelity requires exactness.
302 pub text: String,
303}
304
305/// The last `turn/completed` the session-view fold applied, restated on
306/// `session/resume` and `session/read` so a reopened session can report a
307/// failed last turn.
308#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
309#[serde(rename_all = "camelCase")]
310#[non_exhaustive]
311pub struct LastTurn {
312 /// The turn's id, as on its `turn/completed`; clients deduplicate a live
313 /// `turn/completed` against this member by it.
314 pub turn_id: String,
315 /// The turn's terminal.
316 pub terminal: TurnTerminal,
317 /// Copied when the `turn/completed` carried it; a synthesized host-death
318 /// `failed` terminal carries only this (`crash`, `crash_inferred`, or
319 /// `incomplete`). Free display text: clients never branch on it.
320 #[serde(default, skip_serializing_if = "Option::is_none")]
321 pub reason: Option<String>,
322 /// Copied when the `turn/completed` carried it: runtime `failed` terminals
323 /// do, host-death `failed` terminals do not.
324 #[serde(default, skip_serializing_if = "Option::is_none")]
325 pub error: Option<TurnError>,
326}