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. An equal or tighter choice is what the session runs and reports,
132 /// with two exceptions refused `-32602`: on a daemon whose default sandbox
133 /// is off, a start naming `sandboxEnabled: true` without `sandboxNetwork`,
134 /// or a network restriction (`restricted` or `proxy-only`) without naming
135 /// `sandboxEnabled`, until a tracked change settles how a session turns the
136 /// sandbox on there, and a network restriction beside an explicit
137 /// `sandboxEnabled: false`, which never turns it on and stays refused while
138 /// a tracked change is open: drop the restriction, since a sandbox-off
139 /// session has no network to restrict (`data.reason:
140 /// "tighterSandboxUnserved"` for all three); and under `--trust-workspace
141 /// --listen` without `--allow-session-posture`, an explicit
142 /// `workspaceTrusted: false`, naming the axis. Elsewhere a network
143 /// restriction beside `sandboxEnabled: false` restricts nothing: with the
144 /// sandbox off the network is not sandboxed (`sandboxNetwork` reports
145 /// `enabled`).
146 #[serde(skip_serializing_if = "Option::is_none")]
147 pub limits: Option<SessionLimitsChoice>,
148 /// The `/new` predecessor link: the outgoing session this start succeeds.
149 /// Any syntactically valid session UUID; there is no existence check, so a
150 /// link to a session that is gone still commits. Omitted means a true root.
151 /// Explicit `null` is invalid params.
152 #[serde(
153 default,
154 deserialize_with = "super::deserialize_non_null_optional",
155 skip_serializing_if = "Option::is_none"
156 )]
157 pub previous_session_id: Option<String>,
158 /// Marks this start as a `/clear`: `true` starts the new session as a
159 /// clear, so its `SessionStart` hooks get source `clear` instead of
160 /// `startup`. `false` and omitted are the same plain start (source
161 /// `startup`). It neither needs nor implies `previousSessionId`. Explicit
162 /// `null` is invalid params.
163 #[serde(
164 default,
165 deserialize_with = "super::deserialize_non_null_optional",
166 skip_serializing_if = "Option::is_none"
167 )]
168 pub clear: Option<bool>,
169 /// What happens to the `previousSessionId` predecessor's unfinished
170 /// background work. **Experimental** (`session/start.switchPolicy`; unopted
171 /// callers are refused `-32602`). `kill` cancels the predecessor's
172 /// unfinished work once the new start is durable, as the gate-off `/new`
173 /// does; `keep` ends its persistent monitors only. A policy without the
174 /// link is invalid params, and so is explicit `null`. Omitted means no
175 /// policy: the start records `keep`, exactly as today.
176 #[serde(
177 default,
178 deserialize_with = "super::deserialize_non_null_optional",
179 skip_serializing_if = "Option::is_none"
180 )]
181 pub switch_policy: Option<SwitchPolicy>,
182 /// The nodes this session's tool calls run on, in the order that sets the
183 /// default. **Experimental** (`session/start.nodes`; unopted callers are
184 /// refused `-32602`). Each is attached before the start answers; a start in
185 /// which one fails to attach is refused `commandRejected`
186 /// (`node_attach_refused`) and leaves no session. A host with the nodes
187 /// feature off refuses the member (`nodes_feature_off`), and so does a host
188 /// that does not offer nodes (`nodes_not_offered`). Omitted means the
189 /// session runs on the host's own machine, exactly as today. Explicit
190 /// `null` is invalid params.
191 #[serde(
192 default,
193 deserialize_with = "super::deserialize_non_null_optional",
194 skip_serializing_if = "Option::is_none"
195 )]
196 pub nodes: Option<Vec<SessionStartNode>>,
197 /// The name of the default node, one of `nodes`. **Experimental**
198 /// (`session/start.defaultNode`; unopted callers are refused `-32602`).
199 /// Omitted means the first node. Without `nodes`, a host that would refuse
200 /// `nodes` refuses it the same way (`nodes_feature_off`,
201 /// `nodes_not_offered`) and a host that attaches nodes answers invalid
202 /// params. Explicit `null` is invalid params.
203 #[serde(
204 default,
205 deserialize_with = "super::deserialize_non_null_optional",
206 skip_serializing_if = "Option::is_none"
207 )]
208 pub default_node: Option<String>,
209}
210
211/// `session/start` result.
212#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
213#[serde(rename_all = "camelCase")]
214#[non_exhaustive]
215pub struct SessionStartResult {
216 /// The new session.
217 pub session: Session,
218 /// The session view head after the start fold; the connection is subscribed
219 /// and receives every view event after this cursor. A deduplicated retry
220 /// returns this same result.
221 pub view_cursor: String,
222 /// What the host did not apply. **Experimental**
223 /// (`session/start.warnings`). Absent when there is nothing to warn about,
224 /// never an empty array.
225 #[serde(default, skip_serializing_if = "Option::is_none")]
226 pub warnings: Option<Vec<SessionLoadWarning>>,
227 /// The roster the session started with. **Experimental**
228 /// (`session/start.nodeRoster`; stripped per-connection for unopted
229 /// callers). Present when the start named nodes, the host attached them and
230 /// the session is still loaded with that roster; a retry answered after
231 /// that omits it. A client that named nodes and reads no echo sends no turn
232 /// to the session.
233 #[serde(default, skip_serializing_if = "Option::is_none")]
234 pub node_roster: Option<SessionStartNodeRoster>,
235 /// The built-in tool set this start runs with, when the request
236 /// spelled `config.allowedBuiltInTools` and the host serves the
237 /// restriction (design kt-2n1z N3): the post-intersection set, `[]`
238 /// when applied-to-empty. Absent = not requested or a pre-feature
239 /// host; an absent echo on a spelled input means unapplied. Declared
240 /// here (P5, kt-kqr8), never filled until the last enforcing piece
241 /// (P8). **Experimental** (`session/start.appliedBuiltInTools`).
242 #[serde(default, skip_serializing_if = "Option::is_none")]
243 pub applied_built_in_tools: Option<Vec<String>>,
244 /// The session MCP servers this start admitted. **Experimental**
245 /// (`session/start.admittedSessionMcpServers`). Present iff the
246 /// request spelled `config.admitSessionMcpServers` and the admission
247 /// gate is open; the value is the effective admitted set — names
248 /// joined and not withheld, `[]` when applied-to-empty. Absent means
249 /// not requested or a pre-feature host. Never filled before the last
250 /// enforcing piece lands, so no host can read "applied" early.
251 #[serde(default, skip_serializing_if = "Option::is_none")]
252 pub admitted_session_mcp_servers: Option<Vec<String>>,
253}
254
255/// One `session/start` or `session/resume` result warning. **Experimental.**
256/// The command succeeded; the warning names what the host did not apply.
257#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
258#[serde(rename_all = "camelCase")]
259#[non_exhaustive]
260pub struct SessionLoadWarning {
261 /// Machine code. `setting_ignored`: this host composes no
262 /// `config.settingsOverrides`, so the named keys were ignored.
263 /// `selection_unavailable`: the session's selection names items it
264 /// cannot have; the session started without them (`items`).
265 pub code: String,
266 /// Human-readable text.
267 pub message: String,
268 /// The `config.settingsOverrides` keys the warning names, as sent, in
269 /// ascending string order.
270 #[serde(default, skip_serializing_if = "Vec::is_empty")]
271 pub keys: Vec<String>,
272 /// For `selection_unavailable`: each selected item with the reason it is
273 /// unavailable.
274 #[serde(default, skip_serializing_if = "Vec::is_empty")]
275 pub items: Vec<SessionLoadWarningItem>,
276}
277
278/// One `selection_unavailable` item. **Experimental.**
279#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
280#[serde(rename_all = "camelCase")]
281#[non_exhaustive]
282pub struct SessionLoadWarningItem {
283 /// The selected item: `plugin:<plugin id>`.
284 pub id: String,
285 /// `not_installed`, `host_disabled`, `enterprise_refused`, or
286 /// `managed_disabled`.
287 pub reason: String,
288}