Skip to main content

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 means today's behavior:
58    /// restore retained authority only, no override. The host restores first,
59    /// then applies the pick in the same pre-marker step; a pick that fails
60    /// admission refuses the resume `commandRejected` (-32030;
61    /// `permission_profile_unknown` / `permission_profile_unavailable`) before
62    /// any durable byte. Explicit `null` is invalid params (the same closed
63    /// null-tolerant set as at start).
64    #[serde(
65        default,
66        deserialize_with = "super::deserialize_non_null_optional",
67        skip_serializing_if = "Option::is_none"
68    )]
69    pub permission_profile: Option<String>,
70    /// The same open construction-time extension object as `session/start`.
71    #[serde(
72        default,
73        deserialize_with = "super::deserialize_non_null_optional",
74        skip_serializing_if = "Option::is_none"
75    )]
76    pub config: Option<SessionConfig>,
77}
78
79/// The `history` request preference of `session/resume`. The forced values
80/// downgrade `anchored` → `inline` → `snapshot` → `none`; under `auto` the full
81/// rung order is anchoredSnapshot → inline → snapshot → elided snapshot → none.
82#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
83#[serde(rename_all = "camelCase")]
84pub enum HistoryPreference {
85    /// Serve the best rung that fits, anchored first.
86    Auto,
87    /// Prefer the full folded item array.
88    Inline,
89    /// Prefer a folded view state plus suffix.
90    Snapshot,
91    /// Prefer a snapshot anchored at the latest installed compaction boundary.
92    Anchored,
93}
94
95/// The `history` envelope shared by `session/resume`, `session/fork`, and
96/// `session/read`.
97#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
98#[serde(rename_all = "camelCase")]
99#[non_exhaustive]
100pub struct SessionHistory {
101    /// What was actually served — never what was asked for.
102    pub mode: HistoryMode,
103    /// The full folded item array when `mode` is `inline`; `null` otherwise.
104    pub items: Option<Vec<Item>>,
105    /// The folded view state when `mode` is `snapshot` or `anchoredSnapshot`;
106    /// `null` otherwise.
107    pub snapshot: Option<ViewSnapshot>,
108    /// Why no history was served — sent exactly when `mode` is `"none"`.
109    #[serde(skip_serializing_if = "Option::is_none")]
110    pub none_reason: Option<HistoryNoneReason>,
111    /// The checkpoint-prune boundary: rows for served items at-or-before
112    /// `through_item_id` in served order predate the selected checkpoint.
113    /// Additive-optional; absence is a non-assertion.
114    #[serde(default, skip_serializing_if = "Option::is_none")]
115    pub checkpoint_boundary: Option<CheckpointBoundary>,
116}
117
118/// A served checkpoint-prune boundary: `through_item_id` names the last
119/// first-opened item that opened strictly before the boundary checkpoint event.
120#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
121#[serde(rename_all = "camelCase")]
122#[non_exhaustive]
123pub struct CheckpointBoundary {
124    /// The last pre-boundary item's id, in served (first-opened) order.
125    pub through_item_id: String,
126}
127
128/// Why a result served `history.mode: "none"`: the server's typed reason for
129/// serving no history. Open on the client side: an absent (older server) or
130/// unknown (newer server) value decodes conservatively as an unknown reason,
131/// and `viewCursor` text never substitutes for it.
132#[derive(Debug, Clone, PartialEq, Eq)]
133#[non_exhaustive]
134pub enum HistoryNoneReason {
135    /// The request's effective `excludeItems` was `true` (the
136    /// `session/read` default; explicit on resume/fork).
137    Excluded,
138    /// A retained cursor was supplied; the streamed suffix carries the
139    /// history.
140    CursorSuffix,
141    /// Every rung through the elided snapshot exceeded the history budget;
142    /// page via `view/page` from the result's `viewCursor`.
143    HistoryBudget,
144    /// No trustworthy materialized projection exists; paging cannot recover it.
145    ProjectionUnavailable,
146    /// The projection exists but the aggregate materialized read exceeded
147    /// its bounded read cap; page in bounded chunks.
148    ProjectionReadLimit,
149    /// A value from a newer host, kept verbatim so an older client decodes the
150    /// rest of the message. Excluded from the generated schema while the enum
151    /// stays declared open; never construct it with a known word.
152    Unknown(String),
153}
154
155/// What history a lifecycle result actually served. Open on the client side:
156/// report-what-was-served means a client treats an unknown mode as "page it
157/// yourself".
158#[derive(Debug, Clone, PartialEq, Eq)]
159#[non_exhaustive]
160pub enum HistoryMode {
161    /// `snapshot` holds a folded view state anchored at the latest installed
162    /// compaction boundary; `snapshot.anchor` names it.
163    AnchoredSnapshot,
164    /// `items` is the full folded item array.
165    Inline,
166    /// `snapshot` holds a folded view state at `snapshot.viewCursor`.
167    Snapshot,
168    /// No history was served — page it via `view/page` from the result's
169    /// `viewCursor`.
170    None,
171    /// A value from a newer host, kept verbatim so an older client decodes the
172    /// rest of the message. Excluded from the generated schema while the enum
173    /// stays declared open; never construct it with a known word.
174    Unknown(String),
175}
176
177/// A late-joiner pointer at an unsettled server-initiated request. The full
178/// payloads arrive as re-issued server-to-client requests right after a
179/// `session/resume` response; `session/read` never re-issues them.
180///
181/// The protocol defines two kind-discriminated entry shapes (`{kind:
182/// "approval", approvalId, viewCursor}` / `{kind: "userInput", userInputId,
183/// viewCursor}`). This type is one flat object with both ids optional, as for
184/// `ApprovalSubject` and `TurnInputPart`, because the v1 model names no
185/// object-variant union; the serialized JSON is the same, but the published
186/// schema also accepts `{"kind":"approval","userInputId":…}` and an entry
187/// carrying no id at all. Unlike `TurnInputPart.type`, `kind` here is an OPEN
188/// enum.
189#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
190#[serde(rename_all = "camelCase")]
191#[non_exhaustive]
192pub struct PendingRequestPointer {
193    /// The discriminator; v1 values `approval` and `userInput`.
194    pub kind: PendingRequestKind,
195    /// Present on an `approval` entry.
196    #[serde(skip_serializing_if = "Option::is_none")]
197    pub approval_id: Option<String>,
198    /// Present on a `userInput` entry.
199    #[serde(skip_serializing_if = "Option::is_none")]
200    pub user_input_id: Option<String>,
201    /// The cursor the request opened at.
202    pub view_cursor: String,
203}
204
205/// The `pendingRequests` discriminator. Open enum, v1 values `approval` and
206/// `userInput`.
207#[derive(Debug, Clone, PartialEq, Eq)]
208#[non_exhaustive]
209pub enum PendingRequestKind {
210    /// An unsettled approval.
211    Approval,
212    /// An unsettled user-input prompt.
213    UserInput,
214    /// A value from a newer host, kept verbatim so an older client decodes the
215    /// rest of the message. Never construct it with a known word.
216    Unknown(String),
217}
218
219/// `session/resume` result.
220#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
221#[serde(rename_all = "camelCase")]
222#[non_exhaustive]
223pub struct SessionResumeResult {
224    /// The loaded session.
225    pub session: Session,
226    /// The session view head; the connection is subscribed after it. A
227    /// still-loaded session a prior `view/unsubscribe` detached is RE-ATTACHED
228    /// by this resume: live delivery resumes from this head. Explicit-cursor
229    /// re-attach with `(after, head]` engine replay stays `view/subscribe`.
230    pub view_cursor: String,
231    /// The served history.
232    pub history: SessionHistory,
233    /// The late-joiner pointer set; empty when nothing is pending.
234    pub pending_requests: Vec<PendingRequestPointer>,
235    /// How the last folded turn ended. **Additive-optional**; absence is a
236    /// non-assertion.
237    #[serde(default, skip_serializing_if = "Option::is_none")]
238    pub last_turn: Option<LastTurn>,
239    /// The axes this resume tightened: when the stored choice exceeds the
240    /// restarted host's narrower ceiling, the resume clamps to fit, carries the
241    /// tightened `currentLimits` on the session, and names each tightened axis
242    /// here. **Experimental, same-user socket only**
243    /// (`session/resume.tightenedAxes`; stripped per-connection for unopted
244    /// callers). Absent when nothing tightened — never an empty array.
245    #[serde(default, skip_serializing_if = "Option::is_none")]
246    pub tightened_axes: Option<Vec<String>>,
247    /// The recallable blocked prompt's refill text. **Additive-optional**;
248    /// absence means no blocked prompt to recall (an unblocked session, or a
249    /// pre-feature host). Data only, never a rendered row: clients seed cold
250    /// recall from it (C-p refills `text`) and MUST NOT display it as history.
251    #[serde(default, skip_serializing_if = "Option::is_none")]
252    pub blocked_prompt: Option<BlockedPrompt>,
253}
254
255/// The cold recall seed on `session/resume` and `session/read` results: at most
256/// one, the latest blocked Main prompt — exactly the host's mirror of
257/// `prompt_recovery::replay::ReplayInput`'s choice.
258#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
259#[serde(rename_all = "camelCase")]
260#[non_exhaustive]
261pub struct BlockedPrompt {
262    /// The exact submitted prompt, verbatim — no truncation, no
263    /// normalization; recall fidelity requires exactness.
264    pub text: String,
265}
266
267/// The last `turn/completed` the session-view fold applied, restated on
268/// `session/resume` and `session/read` so a reopened session can report a
269/// failed last turn.
270#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
271#[serde(rename_all = "camelCase")]
272#[non_exhaustive]
273pub struct LastTurn {
274    /// The turn's id, as on its `turn/completed`; clients deduplicate a live
275    /// `turn/completed` against this member by it.
276    pub turn_id: String,
277    /// The turn's terminal.
278    pub terminal: TurnTerminal,
279    /// Copied when the `turn/completed` carried it; a synthesized host-death
280    /// `failed` terminal carries only this (`crash`, `crash_inferred`, or
281    /// `incomplete`). Free display text: clients never branch on it.
282    #[serde(default, skip_serializing_if = "Option::is_none")]
283    pub reason: Option<String>,
284    /// Copied when the `turn/completed` carried it: runtime `failed` terminals
285    /// do, host-death `failed` terminals do not.
286    #[serde(default, skip_serializing_if = "Option::is_none")]
287    pub error: Option<TurnError>,
288}