muse_code_sdk/msp/method/lifecycle/session_start.rs
1// @generated from the MSP stable schema and protocol sources; do not edit by hand.
2
3use super::RecoveryMode;
4use super::session_mcp::SessionConfig;
5use super::session_start_nodes::SessionStartNode;
6use super::session_start_nodes::SessionStartNodeRoster;
7use super::session_start_switch_policy::SwitchPolicy;
8use crate::msp::method::approval::ClientApprovalRule;
9use crate::msp::method::limits::SessionLimitsChoice;
10use crate::msp::method::session::Session;
11use crate::msp::method::session::SessionSpawnedBy;
12use crate::msp::method::worktree::WorktreeStartRequest;
13use crate::msp::view::state::ApprovalMode;
14use serde::Deserialize;
15use serde::Serialize;
16
17/// `session/start` params.
18#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
19#[serde(rename_all = "camelCase")]
20pub struct SessionStartParams {
21 /// The idempotency handle (UUIDv7). Required; the server never mints one.
22 pub command_id: String,
23 /// Recovery choice for this construction; omission keeps legacy behavior.
24 /// Explicit null is invalid.
25 #[serde(
26 default,
27 deserialize_with = "super::deserialize_non_null_optional",
28 skip_serializing_if = "Option::is_none"
29 )]
30 pub recovery_mode: Option<RecoveryMode>,
31 /// Exact identity for this new root session. When omitted the server mints
32 /// a UUIDv7. This field never selects an existing session: a retained or
33 /// reserved id is rejected `commandRejected` with reason
34 /// `session_id_conflict`.
35 #[serde(skip_serializing_if = "Option::is_none")]
36 pub session_id: Option<String>,
37 /// Absolute path, folded into the first metadata record.
38 #[serde(skip_serializing_if = "Option::is_none")]
39 pub workspace_root: Option<String>,
40 /// The session's initial runtime workspace-root set: ordered absolute
41 /// canonical existing directory paths; the first root is the CWD and plays
42 /// the primary-root role; every root receives the `:workspace_roots` rules;
43 /// extra roots grant no Project Trust. When `workspaceRoot` is also present
44 /// the two must name the same folder, compared on canonical forms, or the
45 /// request is invalid params, and so is explicit `null`. Omitted preserves
46 /// single-root behavior.
47 #[serde(
48 default,
49 deserialize_with = "super::deserialize_non_null_optional",
50 skip_serializing_if = "Option::is_none"
51 )]
52 pub workspace_roots: Option<Vec<String>>,
53 /// Initial model; server default when omitted.
54 #[serde(skip_serializing_if = "Option::is_none")]
55 pub model_id: Option<String>,
56 /// Initial provider routing; server default when omitted or explicit `null`
57 /// — both spellings select the default.
58 #[serde(skip_serializing_if = "Option::is_none")]
59 pub provider_id: Option<String>,
60 /// The session's starting approval mode; server default when omitted or
61 /// explicit `null` — both spellings select the default. Select, never
62 /// create — the value names a mode the host's configuration already
63 /// defines. This is the only surface that declares a non-interactive run's
64 /// policy.
65 #[serde(skip_serializing_if = "Option::is_none")]
66 pub approval_mode: Option<ApprovalMode>,
67 /// The new session's initial permission profile: a profile id the host
68 /// catalog already admits — the rows `permissionProfile/list` serves
69 /// without `sessionId`. Select, never create. Omitted means today's
70 /// behavior: the host's configured default under native admission,
71 /// unchanged. An id the catalog does not carry, or one it serves
72 /// unavailable, refuses the start `commandRejected` (-32030;
73 /// `permission_profile_unknown` / `permission_profile_unavailable`) before
74 /// any durable byte, and an ephemeral host refuses any id
75 /// (`permission_profile_ephemeral_fixed`). `session/fork` does not admit
76 /// the member; `session/resume` admits it as the launch pick. Explicit
77 /// `null` is invalid params: the set of members that tolerate `null` is
78 /// closed and excludes this one, exactly as it excludes `workspaceRoots`.
79 #[serde(
80 default,
81 deserialize_with = "super::deserialize_non_null_optional",
82 skip_serializing_if = "Option::is_none"
83 )]
84 pub permission_profile: Option<String>,
85 /// The session's client-supplied shell prefix allow-rules: `{argvPrefix}`
86 /// objects in the `ShellPrefixSuggestion.argv_prefix` shape. Omitted means
87 /// no client rules. Explicit `null` is invalid params; an empty array is an
88 /// explicit empty set. Until the served-handler slice, a host refuses any
89 /// spelled `approvalRules` on `session/start`/`fork`/`resume` with
90 /// `-32602`; clients omit it. **Experimental**
91 /// (`session/start.approvalRules`).
92 #[serde(
93 default,
94 deserialize_with = "super::deserialize_non_null_optional",
95 skip_serializing_if = "Option::is_none"
96 )]
97 pub approval_rules: Option<Vec<ClientApprovalRule>>,
98 /// Reserved for future per-session overrides; only its `mcpServers` member
99 /// is admitted.
100 #[serde(
101 default,
102 deserialize_with = "super::deserialize_non_null_optional",
103 skip_serializing_if = "Option::is_none"
104 )]
105 pub config: Option<SessionConfig>,
106 /// The session that opens this one, in the `Session.spawnedBy` shape: a
107 /// spawner that starts a worker session over MSP names its own session
108 /// here. The host writes it once into the new session's creation record, as
109 /// a worker process records its environment hand-over, and `session/list` /
110 /// `session/read` serve it back as `Session.spawnedBy`; `session/resume`
111 /// never takes it. **Additive-optional** and **provenance only**. A value
112 /// the host cannot use (a `parentSessionId` that is not a session id, a
113 /// malformed member) records nothing and never refuses the start; an
114 /// unusable `project` or `thread` is dropped on its own. Hosts that predate
115 /// the member ignore it.
116 #[serde(skip_serializing_if = "Option::is_none")]
117 pub spawned_by: Option<SessionSpawnedBy>,
118 /// Ask for a created worktree or attach an existing one. **Experimental**
119 /// (`session/start.worktree`; unopted callers are refused `-32602`). Absent
120 /// means no worktree — the start proceeds exactly as today.
121 #[serde(skip_serializing_if = "Option::is_none")]
122 pub worktree: Option<WorktreeStartRequest>,
123 /// The per-session restriction: the axes this session chooses, each at or
124 /// below the host ceiling. **Experimental, socket-only**
125 /// (`session/start.limits`; unopted callers are refused `-32602`, as are
126 /// opted callers on hosts with no limits regime). Absent means the default
127 /// on every axis — the daemon default for trust, the daemon's own posture
128 /// for the sandbox axes (the ceiling, unless `--allow-session-posture`
129 /// widens the ceiling above it). A choice wider than the ceiling on any
130 /// axis refuses the start `-32028 limitsAboveMax` naming every too-wide
131 /// axis and the ceiling kind (`error.data.ceilingKind`: the daemon default
132 /// or managed policy). An equal or tighter choice is what the session runs
133 /// and reports, with two exceptions refused `-32602`: on a daemon whose
134 /// default sandbox is off, a start naming `sandboxEnabled: true` without
135 /// `sandboxNetwork`, or a network restriction (`restricted` or
136 /// `proxy-only`) without naming `sandboxEnabled`, until a tracked change
137 /// settles how a session turns the sandbox on there, and a network
138 /// restriction beside an explicit `sandboxEnabled: false`, which never
139 /// turns it on and stays refused while a tracked change is open: drop the
140 /// restriction, since a sandbox-off session has no network to restrict
141 /// (`data.reason: "tighterSandboxUnserved"` for all three); and under
142 /// `--trust-workspace --listen` without `--allow-session-posture`, an
143 /// explicit `workspaceTrusted: false`, naming the axis. Elsewhere a network
144 /// restriction beside `sandboxEnabled: false` restricts nothing: with the
145 /// sandbox off the network is not sandboxed (`sandboxNetwork` reports
146 /// `enabled`).
147 #[serde(skip_serializing_if = "Option::is_none")]
148 pub limits: Option<SessionLimitsChoice>,
149 /// The `/new` predecessor link: the outgoing session this start succeeds.
150 /// Any syntactically valid session UUID; there is no existence check, so a
151 /// link to a session that is gone still commits. Omitted means a true root.
152 /// Explicit `null` is invalid params.
153 #[serde(
154 default,
155 deserialize_with = "super::deserialize_non_null_optional",
156 skip_serializing_if = "Option::is_none"
157 )]
158 pub previous_session_id: Option<String>,
159 /// Marks this start as a `/clear`: `true` starts the new session as a
160 /// clear, so its `SessionStart` hooks get source `clear` instead of
161 /// `startup`. `false` and omitted are the same plain start (source
162 /// `startup`). It neither needs nor implies `previousSessionId`. Explicit
163 /// `null` is invalid params.
164 #[serde(
165 default,
166 deserialize_with = "super::deserialize_non_null_optional",
167 skip_serializing_if = "Option::is_none"
168 )]
169 pub clear: Option<bool>,
170 /// What happens to the `previousSessionId` predecessor's unfinished
171 /// background work. **Experimental** (`session/start.switchPolicy`; unopted
172 /// callers are refused `-32602`). `kill` cancels the predecessor's
173 /// unfinished work once the new start is durable, as the gate-off `/new`
174 /// does; `keep` ends its persistent monitors only. A policy without the
175 /// link is invalid params, and so is explicit `null`. Omitted means no
176 /// policy: the start records `keep`, exactly as today.
177 #[serde(
178 default,
179 deserialize_with = "super::deserialize_non_null_optional",
180 skip_serializing_if = "Option::is_none"
181 )]
182 pub switch_policy: Option<SwitchPolicy>,
183 /// The nodes this session's tool calls run on, in the order that sets the
184 /// default. **Experimental** (`session/start.nodes`; unopted callers are
185 /// refused `-32602`). Each is attached before the start answers; a start in
186 /// which one fails to attach is refused `commandRejected`
187 /// (`node_attach_refused`) and leaves no session. A host with the nodes
188 /// feature off refuses the member (`nodes_feature_off`), and so does a host
189 /// that does not offer nodes (`nodes_not_offered`). Omitted means the
190 /// session runs on the host's own machine, exactly as today. Explicit
191 /// `null` is invalid params.
192 #[serde(
193 default,
194 deserialize_with = "super::deserialize_non_null_optional",
195 skip_serializing_if = "Option::is_none"
196 )]
197 pub nodes: Option<Vec<SessionStartNode>>,
198 /// The name of the default node, one of `nodes`. **Experimental**
199 /// (`session/start.defaultNode`; unopted callers are refused `-32602`).
200 /// Omitted means the first node. Without `nodes`, a host that would refuse
201 /// `nodes` refuses it the same way (`nodes_feature_off`,
202 /// `nodes_not_offered`) and a host that attaches nodes answers invalid
203 /// params. Explicit `null` is invalid params.
204 #[serde(
205 default,
206 deserialize_with = "super::deserialize_non_null_optional",
207 skip_serializing_if = "Option::is_none"
208 )]
209 pub default_node: Option<String>,
210}
211
212/// `session/start` result.
213#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
214#[serde(rename_all = "camelCase")]
215#[non_exhaustive]
216pub struct SessionStartResult {
217 /// The new session.
218 pub session: Session,
219 /// The session view head after the start fold; the connection is subscribed
220 /// and receives every view event after this cursor. A deduplicated retry
221 /// returns this same result.
222 pub view_cursor: String,
223 /// What the host did not apply. **Experimental**
224 /// (`session/start.warnings`). Absent when there is nothing to warn about,
225 /// never an empty array.
226 #[serde(default, skip_serializing_if = "Option::is_none")]
227 pub warnings: Option<Vec<SessionLoadWarning>>,
228 /// The roster the session started with. **Experimental**
229 /// (`session/start.nodeRoster`; stripped per-connection for unopted
230 /// callers). Present when the start named nodes, the host attached them and
231 /// the session is still loaded with that roster; a retry answered after
232 /// that omits it. A client that named nodes and reads no echo sends no turn
233 /// to the session.
234 #[serde(default, skip_serializing_if = "Option::is_none")]
235 pub node_roster: Option<SessionStartNodeRoster>,
236 /// The built-in tool set this start runs with, when the request
237 /// spelled `config.allowedBuiltInTools` and the host serves the
238 /// restriction (design kt-2n1z N3): the post-intersection set, `[]`
239 /// when applied-to-empty. Absent = not requested or a pre-feature
240 /// host; an absent echo on a spelled input means unapplied. Declared
241 /// here (P5, kt-kqr8), never filled until the last enforcing piece
242 /// (P8). **Experimental** (`session/start.appliedBuiltInTools`).
243 #[serde(default, skip_serializing_if = "Option::is_none")]
244 pub applied_built_in_tools: Option<Vec<String>>,
245 /// The session MCP servers this start admitted. **Experimental**
246 /// (`session/start.admittedSessionMcpServers`). Present iff the
247 /// request spelled `config.admitSessionMcpServers` and the admission
248 /// gate is open; the value is the effective admitted set — names
249 /// joined and not withheld, `[]` when applied-to-empty. Absent means
250 /// not requested or a pre-feature host. Never filled before the last
251 /// enforcing piece lands, so no host can read "applied" early.
252 #[serde(default, skip_serializing_if = "Option::is_none")]
253 pub admitted_session_mcp_servers: Option<Vec<String>>,
254}
255
256/// One `session/start` or `session/resume` result warning. **Experimental.**
257/// The command succeeded; the warning names what the host did not apply.
258#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
259#[serde(rename_all = "camelCase")]
260#[non_exhaustive]
261pub struct SessionLoadWarning {
262 /// Machine code. `setting_ignored`: this host composes no
263 /// `config.settingsOverrides`, so the named keys were ignored.
264 /// `selection_unavailable`: the session's selection names items it
265 /// cannot have; the session started without them (`items`).
266 pub code: String,
267 /// Human-readable text.
268 pub message: String,
269 /// The `config.settingsOverrides` keys the warning names, as sent, in
270 /// ascending string order.
271 #[serde(default, skip_serializing_if = "Vec::is_empty")]
272 pub keys: Vec<String>,
273 /// For `selection_unavailable`: each selected item with the reason it is
274 /// unavailable.
275 #[serde(default, skip_serializing_if = "Vec::is_empty")]
276 pub items: Vec<SessionLoadWarningItem>,
277}
278
279/// One `selection_unavailable` item. **Experimental.**
280#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
281#[serde(rename_all = "camelCase")]
282#[non_exhaustive]
283pub struct SessionLoadWarningItem {
284 /// The selected item: `plugin:<plugin id>`.
285 pub id: String,
286 /// `not_installed`, `host_disabled`, `enterprise_refused`, or
287 /// `managed_disabled`.
288 pub reason: String,
289}