Skip to main content

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}