Skip to main content

agent_client_protocol_schema/v1/
agent.rs

1//! Methods and notifications the agent handles/receives.
2//!
3//! This module defines the Agent trait and all associated types for implementing
4//! an AI coding agent that follows the Agent Client Protocol (ACP).
5
6use std::{path::PathBuf, sync::Arc};
7
8use std::collections::HashMap;
9
10use derive_more::{Display, From};
11#[cfg(feature = "unstable_llm_providers")]
12use indexmap::IndexMap;
13use serde::{Deserialize, Serialize};
14use serde_with::{DefaultOnError, DefaultOnNull, VecSkipError, serde_as, skip_serializing_none};
15
16use crate::{IntoOption, ProtocolVersion};
17
18#[cfg(all(
19    feature = "unstable_session_fork",
20    feature = "unstable_session_cursors"
21))]
22use super::CursorId;
23
24use super::{
25    ClientCapabilities, ContentBlock, ExtNotification, ExtRequest, ExtResponse, Meta, SessionId,
26};
27
28#[cfg(all(feature = "unstable_auth_status", feature = "schemars"))]
29use super::AUTH_STATUS_UPDATE_NOTIFICATION;
30#[cfg(feature = "unstable_mcp_over_acp")]
31use super::mcp::{MCP_MESSAGE_METHOD_NAME, MessageMcpNotification};
32
33// Initialize
34
35/// Request parameters for the initialize method.
36///
37/// Sent by the client to establish connection and negotiate capabilities.
38///
39/// See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/v1/initialization)
40#[serde_as]
41#[skip_serializing_none]
42#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
43#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
44#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = INITIALIZE_METHOD_NAME)))]
45#[serde(rename_all = "camelCase")]
46#[non_exhaustive]
47pub struct InitializeRequest {
48    /// The latest protocol version supported by the client.
49    pub protocol_version: ProtocolVersion,
50    /// Capabilities supported by the client.
51    #[serde_as(deserialize_as = "DefaultOnError")]
52    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
53    #[serde(default)]
54    pub client_capabilities: ClientCapabilities,
55    /// Information about the Client name and version sent to the Agent.
56    ///
57    /// Note: in future versions of the protocol, this will be required.
58    #[serde_as(deserialize_as = "DefaultOnError")]
59    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
60    #[serde(default)]
61    pub client_info: Option<Implementation>,
62    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
63    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
64    /// these keys.
65    ///
66    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
67    #[serde_as(deserialize_as = "DefaultOnError")]
68    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
69    #[serde(default)]
70    #[serde(rename = "_meta")]
71    pub meta: Option<Meta>,
72}
73
74impl InitializeRequest {
75    /// Builds [`InitializeRequest`] with the required request fields set. Optional fields start unset or empty.
76    #[must_use]
77    pub fn new(protocol_version: ProtocolVersion) -> Self {
78        Self {
79            protocol_version,
80            client_capabilities: ClientCapabilities::default(),
81            client_info: None,
82            meta: None,
83        }
84    }
85
86    /// Capabilities supported by the client.
87    #[must_use]
88    pub fn client_capabilities(mut self, client_capabilities: ClientCapabilities) -> Self {
89        self.client_capabilities = client_capabilities;
90        self
91    }
92
93    /// Information about the Client name and version sent to the Agent.
94    #[must_use]
95    pub fn client_info(mut self, client_info: impl IntoOption<Implementation>) -> Self {
96        self.client_info = client_info.into_option();
97        self
98    }
99
100    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
101    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
102    /// these keys.
103    ///
104    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
105    #[must_use]
106    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
107        self.meta = meta.into_option();
108        self
109    }
110}
111
112/// Response to the `initialize` method.
113///
114/// Contains the negotiated protocol version and agent capabilities.
115///
116/// See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/v1/initialization)
117#[serde_as]
118#[skip_serializing_none]
119#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
120#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
121#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = INITIALIZE_METHOD_NAME)))]
122#[serde(rename_all = "camelCase")]
123#[non_exhaustive]
124pub struct InitializeResponse {
125    /// The protocol version the client specified if supported by the agent,
126    /// or the latest protocol version supported by the agent.
127    ///
128    /// The client SHOULD disconnect, if it doesn't support this version.
129    pub protocol_version: ProtocolVersion,
130    /// Capabilities supported by the agent.
131    #[serde_as(deserialize_as = "DefaultOnError")]
132    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
133    #[serde(default)]
134    pub agent_capabilities: AgentCapabilities,
135    /// Authentication methods supported by the agent.
136    #[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_>>")]
137    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
138    #[serde(default)]
139    pub auth_methods: Vec<AuthMethod>,
140    /// Information about the Agent name and version sent to the Client.
141    ///
142    /// Note: in future versions of the protocol, this will be required.
143    #[serde_as(deserialize_as = "DefaultOnError")]
144    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
145    #[serde(default)]
146    pub agent_info: Option<Implementation>,
147    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
148    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
149    /// these keys.
150    ///
151    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
152    #[serde_as(deserialize_as = "DefaultOnError")]
153    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
154    #[serde(default)]
155    #[serde(rename = "_meta")]
156    pub meta: Option<Meta>,
157}
158
159impl InitializeResponse {
160    /// Builds [`InitializeResponse`] with the required response fields set. Optional fields start unset or empty.
161    #[must_use]
162    pub fn new(protocol_version: ProtocolVersion) -> Self {
163        Self {
164            protocol_version,
165            agent_capabilities: AgentCapabilities::default(),
166            auth_methods: vec![],
167            agent_info: None,
168            meta: None,
169        }
170    }
171
172    /// Capabilities supported by the agent.
173    #[must_use]
174    pub fn agent_capabilities(mut self, agent_capabilities: AgentCapabilities) -> Self {
175        self.agent_capabilities = agent_capabilities;
176        self
177    }
178
179    /// Authentication methods supported by the agent.
180    #[must_use]
181    pub fn auth_methods(mut self, auth_methods: Vec<AuthMethod>) -> Self {
182        self.auth_methods = auth_methods;
183        self
184    }
185
186    /// Information about the Agent name and version sent to the Client.
187    #[must_use]
188    pub fn agent_info(mut self, agent_info: impl IntoOption<Implementation>) -> Self {
189        self.agent_info = agent_info.into_option();
190        self
191    }
192
193    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
194    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
195    /// these keys.
196    ///
197    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
198    #[must_use]
199    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
200        self.meta = meta.into_option();
201        self
202    }
203}
204
205/// Metadata about the implementation of the client or agent.
206/// Describes the name and version of an ACP implementation, with an optional
207/// title for UI representation.
208#[serde_as]
209#[skip_serializing_none]
210#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
211#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
212#[serde(rename_all = "camelCase")]
213#[non_exhaustive]
214pub struct Implementation {
215    /// Intended for programmatic or logical use, but can be used as a display
216    /// name fallback if title isn't present.
217    pub name: String,
218    /// Intended for UI and end-user contexts and optimized to be human-readable
219    /// and easily understood.
220    ///
221    /// If not provided, the name SHOULD be used for display.
222    #[serde_as(deserialize_as = "DefaultOnError")]
223    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
224    #[serde(default)]
225    pub title: Option<String>,
226    /// Version of the implementation. Can be displayed to the user or used
227    /// for debugging or metrics purposes. (e.g. "1.0.0").
228    pub version: String,
229    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
230    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
231    /// these keys.
232    ///
233    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
234    #[serde_as(deserialize_as = "DefaultOnError")]
235    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
236    #[serde(default)]
237    #[serde(rename = "_meta")]
238    pub meta: Option<Meta>,
239}
240
241impl Implementation {
242    /// Builds [`Implementation`] with the required fields set. Optional fields start unset or empty.
243    #[must_use]
244    pub fn new(name: impl Into<String>, version: impl Into<String>) -> Self {
245        Self {
246            name: name.into(),
247            title: None,
248            version: version.into(),
249            meta: None,
250        }
251    }
252
253    /// Intended for UI and end-user contexts and optimized to be human-readable
254    /// and easily understood.
255    ///
256    /// If not provided, the name SHOULD be used for display.
257    #[must_use]
258    pub fn title(mut self, title: impl IntoOption<String>) -> Self {
259        self.title = title.into_option();
260        self
261    }
262
263    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
264    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
265    /// these keys.
266    ///
267    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
268    #[must_use]
269    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
270        self.meta = meta.into_option();
271        self
272    }
273}
274
275// Authentication
276
277/// Request parameters for the authenticate method.
278///
279/// Specifies which authentication method to use.
280#[serde_as]
281#[skip_serializing_none]
282#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
283#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
284#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = AUTHENTICATE_METHOD_NAME)))]
285#[serde(rename_all = "camelCase")]
286#[non_exhaustive]
287pub struct AuthenticateRequest {
288    /// The ID of the authentication method to use.
289    /// Must be one of the methods advertised in the initialize response.
290    pub method_id: AuthMethodId,
291    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
292    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
293    /// these keys.
294    ///
295    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
296    #[serde_as(deserialize_as = "DefaultOnError")]
297    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
298    #[serde(default)]
299    #[serde(rename = "_meta")]
300    pub meta: Option<Meta>,
301}
302
303impl AuthenticateRequest {
304    /// Builds [`AuthenticateRequest`] with the required request fields set. Optional fields start unset or empty.
305    #[must_use]
306    pub fn new(method_id: impl Into<AuthMethodId>) -> Self {
307        Self {
308            method_id: method_id.into(),
309            meta: None,
310        }
311    }
312
313    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
314    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
315    /// these keys.
316    ///
317    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
318    #[must_use]
319    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
320        self.meta = meta.into_option();
321        self
322    }
323}
324
325crate::serde_util::default_on_null! {
326    /// Response to the `authenticate` method.
327    #[serde_as]
328    #[skip_serializing_none]
329    #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
330    #[derive(Default, Debug, Clone, Serialize, PartialEq, Eq)]
331    #[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = AUTHENTICATE_METHOD_NAME)))]
332    #[serde(rename_all = "camelCase")]
333    #[non_exhaustive]
334    pub struct AuthenticateResponse {
335        /// The _meta property is reserved by ACP to allow clients and agents to attach additional
336        /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
337        /// these keys.
338        ///
339        /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
340        #[serde_as(deserialize_as = "DefaultOnError")]
341        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
342        #[serde(default)]
343        #[serde(rename = "_meta")]
344        pub meta: Option<Meta>,
345    }
346}
347
348impl AuthenticateResponse {
349    /// Builds [`AuthenticateResponse`] with the required response fields set. Optional fields start unset or empty.
350    #[must_use]
351    pub fn new() -> Self {
352        Self::default()
353    }
354
355    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
356    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
357    /// these keys.
358    ///
359    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
360    #[must_use]
361    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
362        self.meta = meta.into_option();
363        self
364    }
365}
366
367// Logout
368
369crate::serde_util::default_on_null! {
370    /// Request parameters for the logout method.
371    ///
372    /// Terminates the current authenticated session.
373    #[serde_as]
374    #[skip_serializing_none]
375    #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
376    #[derive(Default, Debug, Clone, Serialize, PartialEq, Eq)]
377    #[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = LOGOUT_METHOD_NAME)))]
378    #[serde(rename_all = "camelCase")]
379    #[non_exhaustive]
380    pub struct LogoutRequest {
381        /// The _meta property is reserved by ACP to allow clients and agents to attach additional
382        /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
383        /// these keys.
384        ///
385        /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
386        #[serde_as(deserialize_as = "DefaultOnError")]
387        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
388        #[serde(default)]
389        #[serde(rename = "_meta")]
390        pub meta: Option<Meta>,
391    }
392}
393
394impl LogoutRequest {
395    /// Builds [`LogoutRequest`] with the required request fields set. Optional fields start unset or empty.
396    #[must_use]
397    pub fn new() -> Self {
398        Self::default()
399    }
400
401    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
402    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
403    /// these keys.
404    ///
405    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
406    #[must_use]
407    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
408        self.meta = meta.into_option();
409        self
410    }
411}
412
413crate::serde_util::default_on_null! {
414    /// Response to the `logout` method.
415    #[serde_as]
416    #[skip_serializing_none]
417    #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
418    #[derive(Default, Debug, Clone, Serialize, PartialEq, Eq)]
419    #[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = LOGOUT_METHOD_NAME)))]
420    #[serde(rename_all = "camelCase")]
421    #[non_exhaustive]
422    pub struct LogoutResponse {
423        /// The _meta property is reserved by ACP to allow clients and agents to attach additional
424        /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
425        /// these keys.
426        ///
427        /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
428        #[serde_as(deserialize_as = "DefaultOnError")]
429        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
430        #[serde(default)]
431        #[serde(rename = "_meta")]
432        pub meta: Option<Meta>,
433    }
434}
435
436impl LogoutResponse {
437    /// Builds [`LogoutResponse`] with the required response fields set. Optional fields start unset or empty.
438    #[must_use]
439    pub fn new() -> Self {
440        Self::default()
441    }
442
443    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
444    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
445    /// these keys.
446    ///
447    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
448    #[must_use]
449    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
450        self.meta = meta.into_option();
451        self
452    }
453}
454
455// Auth status
456
457#[cfg(feature = "unstable_auth_status")]
458crate::serde_util::default_on_null! {
459    /// **UNSTABLE**
460    ///
461    /// This capability is not part of the spec yet, and may be removed or changed at any point.
462    ///
463    /// Request parameters for the `auth/status` method.
464    ///
465    /// Queries the agent's current authentication state without changing it.
466    ///
467    /// Agents MUST NOT reject it with `auth_required` (`-32000`), since Clients call it to learn
468    /// whether authentication is required.
469    #[serde_as]
470    #[skip_serializing_none]
471    #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
472    #[derive(Default, Debug, Clone, Serialize, PartialEq, Eq)]
473    #[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = AUTH_STATUS_METHOD_NAME)))]
474    #[serde(rename_all = "camelCase")]
475    #[non_exhaustive]
476    pub struct AuthStatusRequest {
477        /// The _meta property is reserved by ACP to allow clients and agents to attach additional
478        /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
479        /// these keys.
480        ///
481        /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
482        #[serde_as(deserialize_as = "DefaultOnError")]
483        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
484        #[serde(default)]
485        #[serde(rename = "_meta")]
486        pub meta: Option<Meta>,
487    }
488}
489
490#[cfg(feature = "unstable_auth_status")]
491impl AuthStatusRequest {
492    /// Builds [`AuthStatusRequest`] with the required request fields set. Optional fields start unset or empty.
493    #[must_use]
494    pub fn new() -> Self {
495        Self::default()
496    }
497
498    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
499    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
500    /// these keys.
501    ///
502    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
503    #[must_use]
504    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
505        self.meta = meta.into_option();
506        self
507    }
508}
509
510/// **UNSTABLE**
511///
512/// This capability is not part of the spec yet, and may be removed or changed at any point.
513///
514/// Response to the `auth/status` method.
515#[cfg(feature = "unstable_auth_status")]
516#[serde_as]
517#[skip_serializing_none]
518#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
519#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
520#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = AUTH_STATUS_METHOD_NAME)))]
521#[serde(rename_all = "camelCase")]
522#[non_exhaustive]
523pub struct AuthStatusResponse {
524    /// Whether the agent can start sessions without the user signing in first.
525    ///
526    /// Clients use this field to decide whether sign-in is needed. Clients MUST treat
527    /// values they do not recognize as `unknown`.
528    pub state: AuthState,
529    /// The accounts the agent has configured, for display.
530    ///
531    /// Optional. Omitted and empty are equivalent and mean no accounts are reported.
532    /// Agents that hold credentials for several providers or accounts SHOULD list each
533    /// of them and mark the ones in effect with `active`.
534    #[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_>>")]
535    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
536    #[serde(default, skip_serializing_if = "Vec::is_empty")]
537    pub accounts: Vec<AuthAccount>,
538    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
539    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
540    /// these keys.
541    ///
542    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
543    #[serde_as(deserialize_as = "DefaultOnError")]
544    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
545    #[serde(default)]
546    #[serde(rename = "_meta")]
547    pub meta: Option<Meta>,
548}
549
550#[cfg(feature = "unstable_auth_status")]
551impl AuthStatusResponse {
552    /// Builds [`AuthStatusResponse`] with the required fields set. Optional fields start unset or empty.
553    #[must_use]
554    pub fn new(state: AuthState) -> Self {
555        Self {
556            state,
557            accounts: vec![],
558            meta: None,
559        }
560    }
561
562    /// The accounts the agent has configured, for display.
563    #[must_use]
564    pub fn accounts(mut self, accounts: Vec<AuthAccount>) -> Self {
565        self.accounts = accounts;
566        self
567    }
568
569    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
570    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
571    /// these keys.
572    ///
573    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
574    #[must_use]
575    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
576        self.meta = meta.into_option();
577        self
578    }
579}
580
581/// **UNSTABLE**
582///
583/// This capability is not part of the spec yet, and may be removed or changed at any point.
584///
585/// Notification sent by the agent when its authentication status changes.
586///
587/// Carries the same fields as the `auth/status` response. Agents that advertise the
588/// `auth.status` capability MAY send it at any time after `initialize`, and SHOULD only
589/// send it when the reported status differs from the last one sent on the connection.
590#[cfg(feature = "unstable_auth_status")]
591#[serde_as]
592#[skip_serializing_none]
593#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
594#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
595#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "client", "x-method" = AUTH_STATUS_UPDATE_NOTIFICATION)))]
596#[serde(rename_all = "camelCase")]
597#[non_exhaustive]
598pub struct AuthStatusUpdateNotification {
599    /// Whether the agent can start sessions without the user signing in first.
600    ///
601    /// Clients use this field to decide whether sign-in is needed. Clients MUST treat
602    /// values they do not recognize as `unknown`.
603    pub state: AuthState,
604    /// The accounts the agent has configured, for display.
605    ///
606    /// Optional. Omitted and empty are equivalent and mean no accounts are reported.
607    /// Agents that hold credentials for several providers or accounts SHOULD list each
608    /// of them and mark the ones in effect with `active`.
609    #[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_>>")]
610    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
611    #[serde(default, skip_serializing_if = "Vec::is_empty")]
612    pub accounts: Vec<AuthAccount>,
613    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
614    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
615    /// these keys.
616    ///
617    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
618    #[serde_as(deserialize_as = "DefaultOnError")]
619    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
620    #[serde(default)]
621    #[serde(rename = "_meta")]
622    pub meta: Option<Meta>,
623}
624
625#[cfg(feature = "unstable_auth_status")]
626impl AuthStatusUpdateNotification {
627    /// Builds [`AuthStatusUpdateNotification`] with the required fields set. Optional fields start unset or empty.
628    #[must_use]
629    pub fn new(state: AuthState) -> Self {
630        Self {
631            state,
632            accounts: vec![],
633            meta: None,
634        }
635    }
636
637    /// The accounts the agent has configured, for display.
638    #[must_use]
639    pub fn accounts(mut self, accounts: Vec<AuthAccount>) -> Self {
640        self.accounts = accounts;
641        self
642    }
643
644    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
645    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
646    /// these keys.
647    ///
648    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
649    #[must_use]
650    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
651        self.meta = meta.into_option();
652        self
653    }
654}
655
656/// **UNSTABLE**
657///
658/// This capability is not part of the spec yet, and may be removed or changed at any point.
659///
660/// The agent's overall authentication state.
661#[cfg(feature = "unstable_auth_status")]
662#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
663#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
664#[serde(rename_all = "snake_case")]
665#[non_exhaustive]
666pub enum AuthState {
667    /// Credentials are configured. This does not guarantee that they are valid.
668    Authenticated,
669    /// The user needs to sign in. This includes credentials that are missing,
670    /// expired, or known to be invalid.
671    Unauthenticated,
672    /// No authentication is needed, for example because the agent uses a local model.
673    NotRequired,
674    /// The agent cannot currently determine the state.
675    Unknown,
676    /// Custom or future authentication state.
677    ///
678    /// Values beginning with `_` are reserved for implementation-specific
679    /// extensions. Unknown values that do not begin with `_` are reserved for
680    /// future ACP variants.
681    #[serde(untagged)]
682    Other(String),
683}
684
685/// **UNSTABLE**
686///
687/// This capability is not part of the spec yet, and may be removed or changed at any point.
688///
689/// An account or credential the agent has configured, such as a signed-in user
690/// account or an API key.
691///
692/// All fields are display information only. Clients MUST NOT use them as stable
693/// account identifiers, and SHOULD NOT log them or send them elsewhere, such as to
694/// telemetry.
695#[cfg(feature = "unstable_auth_status")]
696#[serde_as]
697#[skip_serializing_none]
698#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
699#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
700#[serde(rename_all = "camelCase")]
701#[non_exhaustive]
702pub struct AuthAccount {
703    /// Human-readable name for the account, suitable for display on its own,
704    /// for example `Claude Max`, `OpenAI API key`, or `Vertex AI`.
705    pub label: String,
706    /// Short text shown with the label, such as the credential source, for example
707    /// `API key helper`. MUST NOT contain credentials.
708    ///
709    /// Optional. Omitted and `null` are equivalent and mean no description is reported.
710    #[serde_as(deserialize_as = "DefaultOnError")]
711    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
712    #[serde(default)]
713    pub description: Option<String>,
714    /// Whether the agent currently uses this account by default.
715    ///
716    /// Several accounts MAY be active, for example one per provider.
717    ///
718    /// Optional. Omitted and `null` are equivalent and mean the agent does not indicate whether this account is in effect.
719    #[serde_as(deserialize_as = "DefaultOnError")]
720    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
721    #[serde(default)]
722    pub active: Option<bool>,
723    /// Display name of the user, such as a username or full name.
724    ///
725    /// Optional. Omitted and `null` are equivalent and mean no name is reported.
726    #[serde_as(deserialize_as = "DefaultOnError")]
727    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
728    #[serde(default)]
729    pub name: Option<String>,
730    /// Email address of the user.
731    ///
732    /// Optional. Omitted and `null` are equivalent and mean no email is reported.
733    #[serde_as(deserialize_as = "DefaultOnError")]
734    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
735    #[serde(default)]
736    pub email: Option<String>,
737    /// Display name of the organization, team, or workspace the account is using.
738    ///
739    /// Optional. Omitted and `null` are equivalent and mean no organization is reported.
740    #[serde_as(deserialize_as = "DefaultOnError")]
741    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
742    #[serde(default)]
743    pub organization: Option<String>,
744    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
745    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
746    /// these keys.
747    ///
748    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
749    #[serde_as(deserialize_as = "DefaultOnError")]
750    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
751    #[serde(default)]
752    #[serde(rename = "_meta")]
753    pub meta: Option<Meta>,
754}
755
756#[cfg(feature = "unstable_auth_status")]
757impl AuthAccount {
758    /// Builds [`AuthAccount`] with the required fields set. Optional fields start unset or empty.
759    #[must_use]
760    pub fn new(label: impl Into<String>) -> Self {
761        Self {
762            label: label.into(),
763            description: None,
764            active: None,
765            name: None,
766            email: None,
767            organization: None,
768            meta: None,
769        }
770    }
771
772    /// Short text shown with the label, such as the credential source.
773    #[must_use]
774    pub fn description(mut self, description: impl IntoOption<String>) -> Self {
775        self.description = description.into_option();
776        self
777    }
778
779    /// Whether the agent currently uses this account by default.
780    #[must_use]
781    pub fn active(mut self, active: impl IntoOption<bool>) -> Self {
782        self.active = active.into_option();
783        self
784    }
785
786    /// Display name of the user, such as a username or full name.
787    #[must_use]
788    pub fn name(mut self, name: impl IntoOption<String>) -> Self {
789        self.name = name.into_option();
790        self
791    }
792
793    /// Email address of the user.
794    #[must_use]
795    pub fn email(mut self, email: impl IntoOption<String>) -> Self {
796        self.email = email.into_option();
797        self
798    }
799
800    /// Display name of the organization, team, or workspace the account is using.
801    #[must_use]
802    pub fn organization(mut self, organization: impl IntoOption<String>) -> Self {
803        self.organization = organization.into_option();
804        self
805    }
806
807    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
808    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
809    /// these keys.
810    ///
811    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
812    #[must_use]
813    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
814        self.meta = meta.into_option();
815        self
816    }
817}
818
819/// **UNSTABLE**
820///
821/// This capability is not part of the spec yet, and may be removed or changed at any point.
822///
823/// Auth status capabilities supported by the agent.
824///
825/// Supplying `{}` means the agent supports the `auth/status` method.
826#[cfg(feature = "unstable_auth_status")]
827#[serde_as]
828#[skip_serializing_none]
829#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
830#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
831#[non_exhaustive]
832pub struct AuthStatusCapabilities {
833    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
834    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
835    /// these keys.
836    ///
837    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
838    #[serde_as(deserialize_as = "DefaultOnError")]
839    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
840    #[serde(default)]
841    #[serde(rename = "_meta")]
842    pub meta: Option<Meta>,
843}
844
845#[cfg(feature = "unstable_auth_status")]
846impl AuthStatusCapabilities {
847    /// Builds an empty [`AuthStatusCapabilities`]. Use builder methods to advertise supported sub-capabilities.
848    #[must_use]
849    pub fn new() -> Self {
850        Self::default()
851    }
852
853    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
854    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
855    /// these keys.
856    ///
857    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
858    #[must_use]
859    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
860        self.meta = meta.into_option();
861        self
862    }
863}
864
865/// Authentication-related capabilities supported by the agent.
866#[serde_as]
867#[skip_serializing_none]
868#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
869#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
870#[serde(rename_all = "camelCase")]
871#[non_exhaustive]
872pub struct AgentAuthCapabilities {
873    /// **UNSTABLE**
874    ///
875    /// This capability is not part of the spec yet, and may be removed or changed at any point.
876    ///
877    /// Whether the agent supports the `auth/status` method.
878    ///
879    /// Optional. Omitted or `null` both mean the agent does not advertise support.
880    /// Supplying `{}` means the agent supports the `auth/status` method.
881    #[cfg(feature = "unstable_auth_status")]
882    #[serde_as(deserialize_as = "DefaultOnError")]
883    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
884    #[serde(default)]
885    pub status: Option<AuthStatusCapabilities>,
886    /// Whether the agent supports the logout method.
887    ///
888    /// Optional. Omitted or `null` both mean the agent does not advertise support.
889    /// Supplying `{}` means the agent supports the logout method.
890    #[serde_as(deserialize_as = "DefaultOnError")]
891    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
892    #[serde(default)]
893    pub logout: Option<LogoutCapabilities>,
894    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
895    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
896    /// these keys.
897    ///
898    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
899    #[serde_as(deserialize_as = "DefaultOnError")]
900    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
901    #[serde(default)]
902    #[serde(rename = "_meta")]
903    pub meta: Option<Meta>,
904}
905
906impl AgentAuthCapabilities {
907    /// Builds an empty [`AgentAuthCapabilities`]. Use builder methods to advertise supported sub-capabilities.
908    #[must_use]
909    pub fn new() -> Self {
910        Self::default()
911    }
912
913    /// **UNSTABLE**
914    ///
915    /// This capability is not part of the spec yet, and may be removed or changed at any point.
916    ///
917    /// Whether the agent supports the `auth/status` method.
918    #[cfg(feature = "unstable_auth_status")]
919    #[must_use]
920    pub fn status(mut self, status: impl IntoOption<AuthStatusCapabilities>) -> Self {
921        self.status = status.into_option();
922        self
923    }
924
925    /// Whether the agent supports the logout method.
926    #[must_use]
927    pub fn logout(mut self, logout: impl IntoOption<LogoutCapabilities>) -> Self {
928        self.logout = logout.into_option();
929        self
930    }
931
932    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
933    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
934    /// these keys.
935    ///
936    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
937    #[must_use]
938    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
939        self.meta = meta.into_option();
940        self
941    }
942}
943
944/// Logout capabilities supported by the agent.
945///
946/// Supplying `{}` means the agent supports the logout method.
947#[serde_as]
948#[skip_serializing_none]
949#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
950#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
951#[non_exhaustive]
952pub struct LogoutCapabilities {
953    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
954    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
955    /// these keys.
956    ///
957    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
958    #[serde_as(deserialize_as = "DefaultOnError")]
959    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
960    #[serde(default)]
961    #[serde(rename = "_meta")]
962    pub meta: Option<Meta>,
963}
964
965impl LogoutCapabilities {
966    /// Builds an empty [`LogoutCapabilities`]. Use builder methods to advertise supported sub-capabilities.
967    #[must_use]
968    pub fn new() -> Self {
969        Self::default()
970    }
971
972    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
973    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
974    /// these keys.
975    ///
976    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
977    #[must_use]
978    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
979        self.meta = meta.into_option();
980        self
981    }
982}
983
984/// Typed identifier used for auth method values on the wire.
985#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
986#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, Display, From)]
987#[serde(transparent)]
988#[from(Arc<str>, String, &'static str)]
989#[non_exhaustive]
990pub struct AuthMethodId(pub Arc<str>);
991
992impl AuthMethodId {
993    /// Wraps a protocol string as a typed [`AuthMethodId`].
994    #[must_use]
995    pub fn new(id: impl Into<Arc<str>>) -> Self {
996        Self(id.into())
997    }
998}
999
1000/// Describes an available authentication method.
1001///
1002/// The `type` field acts as the discriminator in the serialized JSON form.
1003/// When no `type` is present, the method is treated as `agent`.
1004#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
1005#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1006#[serde(tag = "type", rename_all = "snake_case")]
1007#[non_exhaustive]
1008pub enum AuthMethod {
1009    /// Client runs the configured agent program as a separate interactive
1010    /// process, without passing this method to `authenticate`.
1011    Terminal(AuthMethodTerminal),
1012    /// Agent handles authentication itself through `authenticate`.
1013    ///
1014    /// This is the default when no `type` is specified.
1015    #[serde(untagged, deserialize_with = "deserialize_agent_auth_method_fallback")]
1016    Agent(AuthMethodAgent),
1017}
1018
1019/// Deserializes the untagged `agent` fallback of [`AuthMethod`].
1020///
1021/// A `terminal` method that fails its own schema must not fall through to
1022/// `agent`, or the client would pass it to `authenticate`.
1023fn deserialize_agent_auth_method_fallback<'de, D>(
1024    deserializer: D,
1025) -> Result<AuthMethodAgent, D::Error>
1026where
1027    D: serde::Deserializer<'de>,
1028{
1029    let value = serde_json::Value::deserialize(deserializer)?;
1030    if value.get("type").and_then(serde_json::Value::as_str) == Some("terminal") {
1031        return Err(serde::de::Error::custom(
1032            "known authentication method `terminal` did not match its schema",
1033        ));
1034    }
1035    AuthMethodAgent::deserialize(value).map_err(serde::de::Error::custom)
1036}
1037
1038impl AuthMethod {
1039    /// The unique identifier for this authentication method.
1040    #[must_use]
1041    pub fn id(&self) -> &AuthMethodId {
1042        match self {
1043            Self::Agent(a) => &a.id,
1044            Self::Terminal(t) => &t.id,
1045        }
1046    }
1047
1048    /// The human-readable name of this authentication method.
1049    #[must_use]
1050    pub fn name(&self) -> &str {
1051        match self {
1052            Self::Agent(a) => &a.name,
1053            Self::Terminal(t) => &t.name,
1054        }
1055    }
1056
1057    /// Optional human-readable description of this authentication method.
1058    #[must_use]
1059    pub fn description(&self) -> Option<&str> {
1060        match self {
1061            Self::Agent(a) => a.description.as_deref(),
1062            Self::Terminal(t) => t.description.as_deref(),
1063        }
1064    }
1065
1066    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
1067    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
1068    /// these keys.
1069    ///
1070    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
1071    #[must_use]
1072    pub fn meta(&self) -> Option<&Meta> {
1073        match self {
1074            Self::Agent(a) => a.meta.as_ref(),
1075            Self::Terminal(t) => t.meta.as_ref(),
1076        }
1077    }
1078}
1079
1080/// Agent handles authentication itself through `authenticate`.
1081///
1082/// This is the default authentication method type.
1083#[serde_as]
1084#[skip_serializing_none]
1085#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
1086#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1087#[serde(rename_all = "camelCase")]
1088#[non_exhaustive]
1089pub struct AuthMethodAgent {
1090    /// Unique identifier for this authentication method.
1091    pub id: AuthMethodId,
1092    /// Human-readable name of the authentication method.
1093    pub name: String,
1094    /// Optional human-readable description of this authentication method.
1095    #[serde_as(deserialize_as = "DefaultOnError")]
1096    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
1097    #[serde(default)]
1098    pub description: Option<String>,
1099    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
1100    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
1101    /// these keys.
1102    ///
1103    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
1104    #[serde_as(deserialize_as = "DefaultOnError")]
1105    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
1106    #[serde(default)]
1107    #[serde(rename = "_meta")]
1108    pub meta: Option<Meta>,
1109}
1110
1111impl AuthMethodAgent {
1112    /// Builds [`AuthMethodAgent`] with the required fields set. Optional fields start unset or empty.
1113    #[must_use]
1114    pub fn new(id: impl Into<AuthMethodId>, name: impl Into<String>) -> Self {
1115        Self {
1116            id: id.into(),
1117            name: name.into(),
1118            description: None,
1119            meta: None,
1120        }
1121    }
1122
1123    /// Optional human-readable description of this authentication method.
1124    #[must_use]
1125    pub fn description(mut self, description: impl IntoOption<String>) -> Self {
1126        self.description = description.into_option();
1127        self
1128    }
1129
1130    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
1131    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
1132    /// these keys.
1133    ///
1134    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
1135    #[must_use]
1136    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
1137        self.meta = meta.into_option();
1138        self
1139    }
1140}
1141
1142/// Terminal-based authentication method.
1143///
1144/// The client runs the configured agent program as a separate interactive
1145/// process for the user to authenticate via a TUI. Agents MUST advertise this
1146/// method only when the client enabled its terminal authentication capability.
1147/// A zero exit status signals success. Any other termination signals failure.
1148/// The client MUST NOT pass this method to `authenticate`.
1149#[serde_as]
1150#[skip_serializing_none]
1151#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
1152#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1153#[serde(rename_all = "camelCase")]
1154#[non_exhaustive]
1155pub struct AuthMethodTerminal {
1156    /// Unique identifier for this authentication method.
1157    pub id: AuthMethodId,
1158    /// Human-readable name of the authentication method.
1159    pub name: String,
1160    /// Optional human-readable description of this authentication method.
1161    #[serde_as(deserialize_as = "DefaultOnError")]
1162    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
1163    #[serde(default)]
1164    pub description: Option<String>,
1165    /// Additional arguments to append to the configured agent invocation for terminal auth.
1166    #[serde_as(deserialize_as = "DefaultOnNull")]
1167    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
1168    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1169    pub args: Vec<String>,
1170    /// Additional environment variables to set on the configured agent invocation for terminal auth.
1171    /// These values override same-named variables in the base launch configuration.
1172    #[serde_as(deserialize_as = "DefaultOnNull")]
1173    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
1174    #[serde(default, skip_serializing_if = "HashMap::is_empty")]
1175    // TODO(next major): use `IndexMap` to keep the key order.
1176    pub env: HashMap<String, String>,
1177    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
1178    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
1179    /// these keys.
1180    ///
1181    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
1182    #[serde_as(deserialize_as = "DefaultOnError")]
1183    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
1184    #[serde(default)]
1185    #[serde(rename = "_meta")]
1186    pub meta: Option<Meta>,
1187}
1188
1189impl AuthMethodTerminal {
1190    /// Builds [`AuthMethodTerminal`] with the required fields set. Optional fields start unset or empty.
1191    #[must_use]
1192    pub fn new(id: impl Into<AuthMethodId>, name: impl Into<String>) -> Self {
1193        Self {
1194            id: id.into(),
1195            name: name.into(),
1196            description: None,
1197            args: Vec::new(),
1198            env: HashMap::new(),
1199            meta: None,
1200        }
1201    }
1202
1203    /// Additional arguments to append to the configured agent invocation for terminal auth.
1204    #[must_use]
1205    pub fn args(mut self, args: Vec<String>) -> Self {
1206        self.args = args;
1207        self
1208    }
1209
1210    /// Additional environment variables to set on the configured agent invocation for terminal auth.
1211    /// These values override same-named variables in the base launch configuration.
1212    #[must_use]
1213    pub fn env(mut self, env: HashMap<String, String>) -> Self {
1214        self.env = env;
1215        self
1216    }
1217
1218    /// Optional human-readable description of this authentication method.
1219    #[must_use]
1220    pub fn description(mut self, description: impl IntoOption<String>) -> Self {
1221        self.description = description.into_option();
1222        self
1223    }
1224
1225    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
1226    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
1227    /// these keys.
1228    ///
1229    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
1230    #[must_use]
1231    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
1232        self.meta = meta.into_option();
1233        self
1234    }
1235}
1236
1237// New session
1238
1239/// Request parameters for creating a new session.
1240///
1241/// See protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/v1/session-setup#creating-a-session)
1242#[serde_as]
1243#[skip_serializing_none]
1244#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
1245#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1246#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_NEW_METHOD_NAME)))]
1247#[serde(rename_all = "camelCase")]
1248#[non_exhaustive]
1249pub struct NewSessionRequest {
1250    /// The working directory for this session. Must be an absolute path.
1251    pub cwd: PathBuf,
1252    /// Additional workspace roots for this session. Each path MUST be absolute.
1253    ///
1254    /// These expand the session's filesystem scope without changing `cwd`, which
1255    /// remains the base for relative paths. When omitted or empty, no
1256    /// additional roots are activated for the new session.
1257    #[serde_as(deserialize_as = "DefaultOnNull")]
1258    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
1259    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1260    pub additional_directories: Vec<PathBuf>,
1261    /// List of MCP (Model Context Protocol) servers the agent should connect to.
1262    #[serde_as(deserialize_as = "DefaultOnNull")]
1263    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
1264    pub mcp_servers: Vec<McpServer>,
1265    /// System-level instructions for the new session.
1266    ///
1267    /// Optional. Omitted and `null` are equivalent and mean the Agent uses its
1268    /// own default instructions. Clients MUST only send this when the Agent
1269    /// advertises `sessionCapabilities.systemPrompt`.
1270    #[serde(default)]
1271    pub system_prompt: Option<SystemPrompt>,
1272    /// **UNSTABLE**
1273    ///
1274    /// This capability is not part of the spec yet, and may be removed or changed at any point.
1275    ///
1276    /// Initial values for the session's config options.
1277    ///
1278    /// Optional. Omitted and `null` are equivalent to an empty list. Clients MUST only send
1279    /// this when the Agent advertises `sessionCapabilities.options`.
1280    ///
1281    /// The Agent applies the entries in list order, as if the Client had called
1282    /// `session/set_config_option` for each entry after the session was set up. Malformed
1283    /// entries and duplicate `configId` values fail the request with `-32602`. The Agent MUST
1284    /// ignore an entry whose `configId` is unknown, whose `type` does not match the option,
1285    /// or whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually
1286    /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries,
1287    /// and SHOULD NOT send other `session/update` notifications caused by applying them
1288    /// before it responds.
1289    #[cfg(feature = "unstable_session_options")]
1290    #[serde_as(deserialize_as = "DefaultOnNull")]
1291    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
1292    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1293    pub config_options: Vec<InitialSessionConfigOption>,
1294    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
1295    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
1296    /// these keys.
1297    ///
1298    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
1299    #[serde_as(deserialize_as = "DefaultOnError")]
1300    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
1301    #[serde(default)]
1302    #[serde(rename = "_meta")]
1303    pub meta: Option<Meta>,
1304}
1305
1306impl NewSessionRequest {
1307    /// Builds [`NewSessionRequest`] with the required request fields set. Optional fields start unset or empty.
1308    #[must_use]
1309    pub fn new(cwd: impl Into<PathBuf>) -> Self {
1310        Self {
1311            cwd: cwd.into(),
1312            additional_directories: vec![],
1313            mcp_servers: vec![],
1314            system_prompt: None,
1315            #[cfg(feature = "unstable_session_options")]
1316            config_options: vec![],
1317            meta: None,
1318        }
1319    }
1320
1321    /// Additional workspace roots for this session. Each path MUST be absolute.
1322    #[must_use]
1323    pub fn additional_directories(mut self, additional_directories: Vec<PathBuf>) -> Self {
1324        self.additional_directories = additional_directories;
1325        self
1326    }
1327
1328    /// List of MCP (Model Context Protocol) servers the agent should connect to.
1329    #[must_use]
1330    pub fn mcp_servers(mut self, mcp_servers: Vec<McpServer>) -> Self {
1331        self.mcp_servers = mcp_servers;
1332        self
1333    }
1334
1335    /// System-level instructions for the new session.
1336    #[must_use]
1337    pub fn system_prompt(mut self, system_prompt: impl IntoOption<SystemPrompt>) -> Self {
1338        self.system_prompt = system_prompt.into_option();
1339        self
1340    }
1341
1342    /// **UNSTABLE**
1343    ///
1344    /// This capability is not part of the spec yet, and may be removed or changed at any point.
1345    ///
1346    /// Initial values for the session's config options.
1347    ///
1348    /// Optional. Omitted and `null` are equivalent to an empty list. Clients MUST only send
1349    /// this when the Agent advertises `sessionCapabilities.options`.
1350    ///
1351    /// The Agent applies the entries in list order, as if the Client had called
1352    /// `session/set_config_option` for each entry after the session was set up. Malformed
1353    /// entries and duplicate `configId` values fail the request with `-32602`. The Agent MUST
1354    /// ignore an entry whose `configId` is unknown, whose `type` does not match the option,
1355    /// or whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually
1356    /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries,
1357    /// and SHOULD NOT send other `session/update` notifications caused by applying them
1358    /// before it responds.
1359    #[cfg(feature = "unstable_session_options")]
1360    #[must_use]
1361    pub fn config_options(mut self, config_options: Vec<InitialSessionConfigOption>) -> Self {
1362        self.config_options = config_options;
1363        self
1364    }
1365
1366    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
1367    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
1368    /// these keys.
1369    ///
1370    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
1371    #[must_use]
1372    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
1373        self.meta = meta.into_option();
1374        self
1375    }
1376}
1377
1378/// Response from creating a new session.
1379///
1380/// See protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/v1/session-setup#creating-a-session)
1381#[serde_as]
1382#[skip_serializing_none]
1383#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
1384#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1385#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_NEW_METHOD_NAME)))]
1386#[serde(rename_all = "camelCase")]
1387#[non_exhaustive]
1388pub struct NewSessionResponse {
1389    /// Unique identifier for the created session.
1390    ///
1391    /// Used in all subsequent requests for this conversation.
1392    pub session_id: SessionId,
1393    /// Initial mode state if supported by the Agent
1394    ///
1395    /// See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/session-modes)
1396    #[serde_as(deserialize_as = "DefaultOnError")]
1397    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
1398    #[serde(default)]
1399    pub modes: Option<SessionModeState>,
1400    /// Initial session configuration options if supported by the Agent.
1401    #[serde_as(deserialize_as = "DefaultOnError<Option<VecSkipError<_>>>")]
1402    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
1403    #[serde(default)]
1404    pub config_options: Option<Vec<SessionConfigOption>>,
1405    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
1406    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
1407    /// these keys.
1408    ///
1409    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
1410    #[serde_as(deserialize_as = "DefaultOnError")]
1411    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
1412    #[serde(default)]
1413    #[serde(rename = "_meta")]
1414    pub meta: Option<Meta>,
1415}
1416
1417impl NewSessionResponse {
1418    /// Builds [`NewSessionResponse`] with the required response fields set. Optional fields start unset or empty.
1419    #[must_use]
1420    pub fn new(session_id: impl Into<SessionId>) -> Self {
1421        Self {
1422            session_id: session_id.into(),
1423            modes: None,
1424            config_options: None,
1425            meta: None,
1426        }
1427    }
1428
1429    /// Initial mode state if supported by the Agent
1430    ///
1431    /// See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/session-modes)
1432    #[must_use]
1433    pub fn modes(mut self, modes: impl IntoOption<SessionModeState>) -> Self {
1434        self.modes = modes.into_option();
1435        self
1436    }
1437
1438    /// Initial session configuration options if supported by the Agent.
1439    #[must_use]
1440    pub fn config_options(
1441        mut self,
1442        config_options: impl IntoOption<Vec<SessionConfigOption>>,
1443    ) -> Self {
1444        self.config_options = config_options.into_option();
1445        self
1446    }
1447
1448    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
1449    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
1450    /// these keys.
1451    ///
1452    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
1453    #[must_use]
1454    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
1455        self.meta = meta.into_option();
1456        self
1457    }
1458}
1459
1460// Load session
1461
1462/// Request parameters for loading an existing session.
1463///
1464/// Only available if the Agent supports the `loadSession` capability.
1465///
1466/// See protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/v1/session-setup#loading-sessions)
1467#[serde_as]
1468#[skip_serializing_none]
1469#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
1470#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1471#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_LOAD_METHOD_NAME)))]
1472#[serde(rename_all = "camelCase")]
1473#[non_exhaustive]
1474pub struct LoadSessionRequest {
1475    /// List of MCP servers to connect to for this session.
1476    #[serde_as(deserialize_as = "DefaultOnNull")]
1477    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
1478    pub mcp_servers: Vec<McpServer>,
1479    /// The working directory for this session. Must be an absolute path.
1480    pub cwd: PathBuf,
1481    /// Additional workspace roots to activate for this session. Each path MUST be absolute.
1482    ///
1483    /// When omitted or empty, no additional roots are activated. When non-empty,
1484    /// this is the complete resulting additional-root list for the loaded
1485    /// session. It MAY differ from any previously used or reported list as long as
1486    /// the request `cwd` matches the session's `cwd`.
1487    #[serde_as(deserialize_as = "DefaultOnNull")]
1488    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
1489    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1490    pub additional_directories: Vec<PathBuf>,
1491    /// The ID of the session to load.
1492    pub session_id: SessionId,
1493    /// System-level instructions for the loaded session.
1494    ///
1495    /// Optional. Omitted and `null` are equivalent. The Agent MAY then keep a
1496    /// system prompt it stored with the session or use its default instructions.
1497    /// Clients MUST only send this when the Agent advertises
1498    /// `sessionCapabilities.systemPrompt`, and SHOULD send the same value they used
1499    /// when the session was created.
1500    #[serde(default)]
1501    pub system_prompt: Option<SystemPrompt>,
1502    /// **UNSTABLE**
1503    ///
1504    /// This capability is not part of the spec yet, and may be removed or changed at any point.
1505    ///
1506    /// Initial values for the session's config options.
1507    ///
1508    /// Optional. Omitted and `null` are equivalent to an empty list. Clients MUST only send
1509    /// this when the Agent advertises `sessionCapabilities.options`.
1510    ///
1511    /// The Agent applies the entries in list order, as if the Client had called
1512    /// `session/set_config_option` for each entry after the session was set up. Malformed
1513    /// entries and duplicate `configId` values fail the request with `-32602`. The Agent MUST
1514    /// ignore an entry whose `configId` is unknown, whose `type` does not match the option,
1515    /// or whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually
1516    /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries.
1517    #[cfg(feature = "unstable_session_options")]
1518    #[serde_as(deserialize_as = "DefaultOnNull")]
1519    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
1520    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1521    pub config_options: Vec<InitialSessionConfigOption>,
1522    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
1523    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
1524    /// these keys.
1525    ///
1526    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
1527    #[serde_as(deserialize_as = "DefaultOnError")]
1528    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
1529    #[serde(default)]
1530    #[serde(rename = "_meta")]
1531    pub meta: Option<Meta>,
1532}
1533
1534impl LoadSessionRequest {
1535    /// Builds [`LoadSessionRequest`] with the required request fields set. Optional fields start unset or empty.
1536    #[must_use]
1537    pub fn new(session_id: impl Into<SessionId>, cwd: impl Into<PathBuf>) -> Self {
1538        Self {
1539            mcp_servers: vec![],
1540            cwd: cwd.into(),
1541            additional_directories: vec![],
1542            session_id: session_id.into(),
1543            system_prompt: None,
1544            #[cfg(feature = "unstable_session_options")]
1545            config_options: vec![],
1546            meta: None,
1547        }
1548    }
1549
1550    /// Additional workspace roots to activate for this session. Each path MUST be absolute.
1551    #[must_use]
1552    pub fn additional_directories(mut self, additional_directories: Vec<PathBuf>) -> Self {
1553        self.additional_directories = additional_directories;
1554        self
1555    }
1556
1557    /// List of MCP servers to connect to for this session.
1558    #[must_use]
1559    pub fn mcp_servers(mut self, mcp_servers: Vec<McpServer>) -> Self {
1560        self.mcp_servers = mcp_servers;
1561        self
1562    }
1563
1564    /// System-level instructions for the loaded session.
1565    #[must_use]
1566    pub fn system_prompt(mut self, system_prompt: impl IntoOption<SystemPrompt>) -> Self {
1567        self.system_prompt = system_prompt.into_option();
1568        self
1569    }
1570
1571    /// **UNSTABLE**
1572    ///
1573    /// This capability is not part of the spec yet, and may be removed or changed at any point.
1574    ///
1575    /// Initial values for the session's config options.
1576    ///
1577    /// Optional. Omitted and `null` are equivalent to an empty list. Clients MUST only send
1578    /// this when the Agent advertises `sessionCapabilities.options`.
1579    ///
1580    /// The Agent applies the entries in list order, as if the Client had called
1581    /// `session/set_config_option` for each entry after the session was set up. Malformed
1582    /// entries and duplicate `configId` values fail the request with `-32602`. The Agent MUST
1583    /// ignore an entry whose `configId` is unknown, whose `type` does not match the option,
1584    /// or whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually
1585    /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries.
1586    #[cfg(feature = "unstable_session_options")]
1587    #[must_use]
1588    pub fn config_options(mut self, config_options: Vec<InitialSessionConfigOption>) -> Self {
1589        self.config_options = config_options;
1590        self
1591    }
1592
1593    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
1594    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
1595    /// these keys.
1596    ///
1597    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
1598    #[must_use]
1599    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
1600        self.meta = meta.into_option();
1601        self
1602    }
1603}
1604
1605crate::serde_util::default_on_null! {
1606    /// Response from loading an existing session.
1607    #[serde_as]
1608    #[skip_serializing_none]
1609    #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
1610    #[derive(Default, Debug, Clone, Serialize, PartialEq, Eq)]
1611    #[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_LOAD_METHOD_NAME)))]
1612    #[serde(rename_all = "camelCase")]
1613    #[non_exhaustive]
1614    pub struct LoadSessionResponse {
1615        /// Initial mode state if supported by the Agent
1616        ///
1617        /// See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/session-modes)
1618        #[serde_as(deserialize_as = "DefaultOnError")]
1619        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
1620        #[serde(default)]
1621        pub modes: Option<SessionModeState>,
1622        /// Initial session configuration options if supported by the Agent.
1623        #[serde_as(deserialize_as = "DefaultOnError<Option<VecSkipError<_>>>")]
1624        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
1625        #[serde(default)]
1626        pub config_options: Option<Vec<SessionConfigOption>>,
1627        /// The _meta property is reserved by ACP to allow clients and agents to attach additional
1628        /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
1629        /// these keys.
1630        ///
1631        /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
1632        #[serde_as(deserialize_as = "DefaultOnError")]
1633        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
1634        #[serde(default)]
1635        #[serde(rename = "_meta")]
1636        pub meta: Option<Meta>,
1637    }
1638}
1639
1640impl LoadSessionResponse {
1641    /// Builds [`LoadSessionResponse`] with the required response fields set. Optional fields start unset or empty.
1642    #[must_use]
1643    pub fn new() -> Self {
1644        Self::default()
1645    }
1646
1647    /// Initial mode state if supported by the Agent
1648    ///
1649    /// See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/session-modes)
1650    #[must_use]
1651    pub fn modes(mut self, modes: impl IntoOption<SessionModeState>) -> Self {
1652        self.modes = modes.into_option();
1653        self
1654    }
1655
1656    /// Initial session configuration options if supported by the Agent.
1657    #[must_use]
1658    pub fn config_options(
1659        mut self,
1660        config_options: impl IntoOption<Vec<SessionConfigOption>>,
1661    ) -> Self {
1662        self.config_options = config_options.into_option();
1663        self
1664    }
1665
1666    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
1667    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
1668    /// these keys.
1669    ///
1670    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
1671    #[must_use]
1672    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
1673        self.meta = meta.into_option();
1674        self
1675    }
1676}
1677
1678// Fork session
1679
1680/// **UNSTABLE**
1681///
1682/// This capability is not part of the spec yet, and may be removed or changed at any point.
1683///
1684/// Request parameters for forking an existing session.
1685///
1686/// Creates a new session based on the context of an existing one, allowing
1687/// operations like generating summaries without affecting the original session's history.
1688///
1689/// Only available if the Agent supports the `session.fork` capability.
1690#[cfg(feature = "unstable_session_fork")]
1691#[serde_as]
1692#[skip_serializing_none]
1693#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
1694#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1695#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_FORK_METHOD_NAME)))]
1696#[serde(rename_all = "camelCase")]
1697#[non_exhaustive]
1698pub struct ForkSessionRequest {
1699    /// The ID of the session to fork.
1700    pub session_id: SessionId,
1701    /// **UNSTABLE**
1702    ///
1703    /// This capability is not part of the spec yet, and may be removed or changed at any point.
1704    ///
1705    /// The session cursor to fork at. The new session's history is the source
1706    /// session's history before the cursor.
1707    ///
1708    /// Optional. Omitted and `null` are equivalent and fork the whole session.
1709    /// Clients MUST only send the ID of a cursor that the Agent announced on the
1710    /// source session and that currently advertises `capabilities.fork`. The Agent
1711    /// rejects any other ID with `-32602`. It does not fall back to forking the
1712    /// whole session.
1713    #[cfg(feature = "unstable_session_cursors")]
1714    #[serde(default)]
1715    pub cursor_id: Option<CursorId>,
1716    /// The working directory for this session. Must be an absolute path.
1717    pub cwd: PathBuf,
1718    /// Additional workspace roots to activate for this session. Each path MUST be absolute.
1719    ///
1720    /// When omitted or empty, no additional roots are activated. When non-empty,
1721    /// this is the complete resulting additional-root list for the forked
1722    /// session.
1723    #[serde_as(deserialize_as = "DefaultOnNull")]
1724    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
1725    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1726    pub additional_directories: Vec<PathBuf>,
1727    /// List of MCP servers to connect to for this session.
1728    #[serde_as(deserialize_as = "DefaultOnNull")]
1729    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
1730    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1731    pub mcp_servers: Vec<McpServer>,
1732    /// System-level instructions for the forked session.
1733    ///
1734    /// Optional. Omitted and `null` are equivalent. The Agent MAY then keep a
1735    /// system prompt it stored with the source session or use its default
1736    /// instructions. Clients MUST only send this when the Agent advertises
1737    /// `sessionCapabilities.systemPrompt`, and SHOULD send the same value they used
1738    /// for the source session.
1739    #[serde(default)]
1740    pub system_prompt: Option<SystemPrompt>,
1741    /// **UNSTABLE**
1742    ///
1743    /// This capability is not part of the spec yet, and may be removed or changed at any point.
1744    ///
1745    /// Initial values for the forked session's config options.
1746    ///
1747    /// Optional. Omitted and `null` are equivalent to an empty list. Clients MUST only send
1748    /// this when the Agent advertises `sessionCapabilities.options`.
1749    ///
1750    /// The Agent applies the entries in list order on top of the configuration the fork
1751    /// starts with, as if the Client had called `session/set_config_option` for each entry
1752    /// after the session was set up. Malformed entries and duplicate `configId` values fail
1753    /// the request with `-32602`. The Agent MUST ignore an entry whose `configId` is unknown,
1754    /// whose `type` does not match the option, or whose value is not allowed when it is
1755    /// applied. The `configOptions` in the response contain the values the session actually
1756    /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries,
1757    /// and SHOULD NOT send other `session/update` notifications caused by applying them
1758    /// before it responds.
1759    #[cfg(feature = "unstable_session_options")]
1760    #[serde_as(deserialize_as = "DefaultOnNull")]
1761    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
1762    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1763    pub config_options: Vec<InitialSessionConfigOption>,
1764    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
1765    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
1766    /// these keys.
1767    ///
1768    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
1769    #[serde_as(deserialize_as = "DefaultOnError")]
1770    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
1771    #[serde(default)]
1772    #[serde(rename = "_meta")]
1773    pub meta: Option<Meta>,
1774}
1775
1776#[cfg(feature = "unstable_session_fork")]
1777impl ForkSessionRequest {
1778    /// Builds [`ForkSessionRequest`] with the required request fields set. Optional fields start unset or empty.
1779    #[must_use]
1780    pub fn new(session_id: impl Into<SessionId>, cwd: impl Into<PathBuf>) -> Self {
1781        Self {
1782            session_id: session_id.into(),
1783            #[cfg(feature = "unstable_session_cursors")]
1784            cursor_id: None,
1785            cwd: cwd.into(),
1786            additional_directories: vec![],
1787            mcp_servers: vec![],
1788            system_prompt: None,
1789            #[cfg(feature = "unstable_session_options")]
1790            config_options: vec![],
1791            meta: None,
1792        }
1793    }
1794
1795    /// **UNSTABLE**
1796    ///
1797    /// This capability is not part of the spec yet, and may be removed or changed at any point.
1798    ///
1799    /// The session cursor to fork at. Omitting it forks the whole session.
1800    ///
1801    /// Clients MUST only send the ID of a cursor that the Agent announced on the
1802    /// source session and that currently advertises `capabilities.fork`.
1803    #[cfg(feature = "unstable_session_cursors")]
1804    #[must_use]
1805    pub fn cursor_id(mut self, cursor_id: impl IntoOption<CursorId>) -> Self {
1806        self.cursor_id = cursor_id.into_option();
1807        self
1808    }
1809
1810    /// Additional workspace roots to activate for this session. Each path MUST be absolute.
1811    #[must_use]
1812    pub fn additional_directories(mut self, additional_directories: Vec<PathBuf>) -> Self {
1813        self.additional_directories = additional_directories;
1814        self
1815    }
1816
1817    /// List of MCP servers to connect to for this session.
1818    #[must_use]
1819    pub fn mcp_servers(mut self, mcp_servers: Vec<McpServer>) -> Self {
1820        self.mcp_servers = mcp_servers;
1821        self
1822    }
1823
1824    /// System-level instructions for the forked session.
1825    #[must_use]
1826    pub fn system_prompt(mut self, system_prompt: impl IntoOption<SystemPrompt>) -> Self {
1827        self.system_prompt = system_prompt.into_option();
1828        self
1829    }
1830
1831    /// **UNSTABLE**
1832    ///
1833    /// This capability is not part of the spec yet, and may be removed or changed at any point.
1834    ///
1835    /// Initial values for the forked session's config options.
1836    ///
1837    /// Optional. Omitted and `null` are equivalent to an empty list. Clients MUST only send
1838    /// this when the Agent advertises `sessionCapabilities.options`.
1839    ///
1840    /// The Agent applies the entries in list order on top of the configuration the fork
1841    /// starts with, as if the Client had called `session/set_config_option` for each entry
1842    /// after the session was set up. Malformed entries and duplicate `configId` values fail
1843    /// the request with `-32602`. The Agent MUST ignore an entry whose `configId` is unknown,
1844    /// whose `type` does not match the option, or whose value is not allowed when it is
1845    /// applied. The `configOptions` in the response contain the values the session actually
1846    /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries,
1847    /// and SHOULD NOT send other `session/update` notifications caused by applying them
1848    /// before it responds.
1849    #[cfg(feature = "unstable_session_options")]
1850    #[must_use]
1851    pub fn config_options(mut self, config_options: Vec<InitialSessionConfigOption>) -> Self {
1852        self.config_options = config_options;
1853        self
1854    }
1855
1856    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
1857    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
1858    /// these keys.
1859    ///
1860    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
1861    #[must_use]
1862    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
1863        self.meta = meta.into_option();
1864        self
1865    }
1866}
1867
1868/// **UNSTABLE**
1869///
1870/// This capability is not part of the spec yet, and may be removed or changed at any point.
1871///
1872/// Response from forking an existing session.
1873#[cfg(feature = "unstable_session_fork")]
1874#[serde_as]
1875#[skip_serializing_none]
1876#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
1877#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1878#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_FORK_METHOD_NAME)))]
1879#[serde(rename_all = "camelCase")]
1880#[non_exhaustive]
1881pub struct ForkSessionResponse {
1882    /// Unique identifier for the newly created forked session.
1883    pub session_id: SessionId,
1884    /// Initial mode state if supported by the Agent
1885    ///
1886    /// See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/session-modes)
1887    #[serde_as(deserialize_as = "DefaultOnError")]
1888    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
1889    #[serde(default)]
1890    pub modes: Option<SessionModeState>,
1891    /// Initial session configuration options if supported by the Agent.
1892    #[serde_as(deserialize_as = "DefaultOnError<Option<VecSkipError<_>>>")]
1893    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
1894    #[serde(default)]
1895    pub config_options: Option<Vec<SessionConfigOption>>,
1896    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
1897    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
1898    /// these keys.
1899    ///
1900    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
1901    #[serde_as(deserialize_as = "DefaultOnError")]
1902    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
1903    #[serde(default)]
1904    #[serde(rename = "_meta")]
1905    pub meta: Option<Meta>,
1906}
1907
1908#[cfg(feature = "unstable_session_fork")]
1909impl ForkSessionResponse {
1910    /// Builds [`ForkSessionResponse`] with the required response fields set. Optional fields start unset or empty.
1911    #[must_use]
1912    pub fn new(session_id: impl Into<SessionId>) -> Self {
1913        Self {
1914            session_id: session_id.into(),
1915            modes: None,
1916            config_options: None,
1917            meta: None,
1918        }
1919    }
1920
1921    /// Initial mode state if supported by the Agent
1922    ///
1923    /// See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/session-modes)
1924    #[must_use]
1925    pub fn modes(mut self, modes: impl IntoOption<SessionModeState>) -> Self {
1926        self.modes = modes.into_option();
1927        self
1928    }
1929
1930    /// Initial session configuration options if supported by the Agent.
1931    #[must_use]
1932    pub fn config_options(
1933        mut self,
1934        config_options: impl IntoOption<Vec<SessionConfigOption>>,
1935    ) -> Self {
1936        self.config_options = config_options.into_option();
1937        self
1938    }
1939
1940    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
1941    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
1942    /// these keys.
1943    ///
1944    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
1945    #[must_use]
1946    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
1947        self.meta = meta.into_option();
1948        self
1949    }
1950}
1951
1952// Resume session
1953
1954/// Request parameters for resuming an existing session.
1955///
1956/// Resumes an existing session without returning previous messages (unlike `session/load`).
1957/// This is useful for agents that can resume sessions but don't implement full session loading.
1958///
1959/// Only available if the Agent supports the `sessionCapabilities.resume` capability.
1960#[serde_as]
1961#[skip_serializing_none]
1962#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
1963#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
1964#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_RESUME_METHOD_NAME)))]
1965#[serde(rename_all = "camelCase")]
1966#[non_exhaustive]
1967pub struct ResumeSessionRequest {
1968    /// The ID of the session to resume.
1969    pub session_id: SessionId,
1970    /// The working directory for this session. Must be an absolute path.
1971    pub cwd: PathBuf,
1972    /// Additional workspace roots to activate for this session. Each path MUST be absolute.
1973    ///
1974    /// When omitted or empty, no additional roots are activated. When non-empty,
1975    /// this is the complete resulting additional-root list for the resumed
1976    /// session. It MAY differ from any previously used or reported list as long as
1977    /// the request `cwd` matches the session's `cwd`.
1978    #[serde_as(deserialize_as = "DefaultOnNull")]
1979    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
1980    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1981    pub additional_directories: Vec<PathBuf>,
1982    /// List of MCP servers to connect to for this session.
1983    #[serde_as(deserialize_as = "DefaultOnNull")]
1984    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
1985    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1986    pub mcp_servers: Vec<McpServer>,
1987    /// System-level instructions for the resumed session.
1988    ///
1989    /// Optional. Omitted and `null` are equivalent. The Agent MAY then keep a
1990    /// system prompt it stored with the session or use its default instructions.
1991    /// Clients MUST only send this when the Agent advertises
1992    /// `sessionCapabilities.systemPrompt`, and SHOULD send the same value they used
1993    /// when the session was created.
1994    #[serde(default)]
1995    pub system_prompt: Option<SystemPrompt>,
1996    /// **UNSTABLE**
1997    ///
1998    /// This capability is not part of the spec yet, and may be removed or changed at any point.
1999    ///
2000    /// Initial values for the session's config options.
2001    ///
2002    /// Optional. Omitted and `null` are equivalent to an empty list. Clients MUST only send
2003    /// this when the Agent advertises `sessionCapabilities.options`.
2004    ///
2005    /// The Agent applies the entries in list order, as if the Client had called
2006    /// `session/set_config_option` for each entry after the session was set up. Malformed
2007    /// entries and duplicate `configId` values fail the request with `-32602`. The Agent MUST
2008    /// ignore an entry whose `configId` is unknown, whose `type` does not match the option,
2009    /// or whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually
2010    /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries.
2011    #[cfg(feature = "unstable_session_options")]
2012    #[serde_as(deserialize_as = "DefaultOnNull")]
2013    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
2014    #[serde(default, skip_serializing_if = "Vec::is_empty")]
2015    pub config_options: Vec<InitialSessionConfigOption>,
2016    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2017    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2018    /// these keys.
2019    ///
2020    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2021    #[serde_as(deserialize_as = "DefaultOnError")]
2022    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
2023    #[serde(default)]
2024    #[serde(rename = "_meta")]
2025    pub meta: Option<Meta>,
2026}
2027
2028impl ResumeSessionRequest {
2029    /// Builds [`ResumeSessionRequest`] with the required request fields set. Optional fields start unset or empty.
2030    #[must_use]
2031    pub fn new(session_id: impl Into<SessionId>, cwd: impl Into<PathBuf>) -> Self {
2032        Self {
2033            session_id: session_id.into(),
2034            cwd: cwd.into(),
2035            additional_directories: vec![],
2036            mcp_servers: vec![],
2037            system_prompt: None,
2038            #[cfg(feature = "unstable_session_options")]
2039            config_options: vec![],
2040            meta: None,
2041        }
2042    }
2043
2044    /// Additional workspace roots to activate for this session. Each path MUST be absolute.
2045    #[must_use]
2046    pub fn additional_directories(mut self, additional_directories: Vec<PathBuf>) -> Self {
2047        self.additional_directories = additional_directories;
2048        self
2049    }
2050
2051    /// List of MCP servers to connect to for this session.
2052    #[must_use]
2053    pub fn mcp_servers(mut self, mcp_servers: Vec<McpServer>) -> Self {
2054        self.mcp_servers = mcp_servers;
2055        self
2056    }
2057
2058    /// System-level instructions for the resumed session.
2059    #[must_use]
2060    pub fn system_prompt(mut self, system_prompt: impl IntoOption<SystemPrompt>) -> Self {
2061        self.system_prompt = system_prompt.into_option();
2062        self
2063    }
2064
2065    /// **UNSTABLE**
2066    ///
2067    /// This capability is not part of the spec yet, and may be removed or changed at any point.
2068    ///
2069    /// Initial values for the session's config options.
2070    ///
2071    /// Optional. Omitted and `null` are equivalent to an empty list. Clients MUST only send
2072    /// this when the Agent advertises `sessionCapabilities.options`.
2073    ///
2074    /// The Agent applies the entries in list order, as if the Client had called
2075    /// `session/set_config_option` for each entry after the session was set up. Malformed
2076    /// entries and duplicate `configId` values fail the request with `-32602`. The Agent MUST
2077    /// ignore an entry whose `configId` is unknown, whose `type` does not match the option,
2078    /// or whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually
2079    /// has. The Agent SHOULD NOT send `config_option_update` notifications for these entries.
2080    #[cfg(feature = "unstable_session_options")]
2081    #[must_use]
2082    pub fn config_options(mut self, config_options: Vec<InitialSessionConfigOption>) -> Self {
2083        self.config_options = config_options;
2084        self
2085    }
2086
2087    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2088    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2089    /// these keys.
2090    ///
2091    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2092    #[must_use]
2093    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
2094        self.meta = meta.into_option();
2095        self
2096    }
2097}
2098
2099crate::serde_util::default_on_null! {
2100    /// Response from resuming an existing session.
2101    #[serde_as]
2102    #[skip_serializing_none]
2103    #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
2104    #[derive(Default, Debug, Clone, Serialize, PartialEq, Eq)]
2105    #[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_RESUME_METHOD_NAME)))]
2106    #[serde(rename_all = "camelCase")]
2107    #[non_exhaustive]
2108    pub struct ResumeSessionResponse {
2109        /// Initial mode state if supported by the Agent
2110        ///
2111        /// See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/session-modes)
2112        #[serde_as(deserialize_as = "DefaultOnError")]
2113        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
2114        #[serde(default)]
2115        pub modes: Option<SessionModeState>,
2116        /// Initial session configuration options if supported by the Agent.
2117        #[serde_as(deserialize_as = "DefaultOnError<Option<VecSkipError<_>>>")]
2118        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
2119        #[serde(default)]
2120        pub config_options: Option<Vec<SessionConfigOption>>,
2121        /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2122        /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2123        /// these keys.
2124        ///
2125        /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2126        #[serde_as(deserialize_as = "DefaultOnError")]
2127        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
2128        #[serde(default)]
2129        #[serde(rename = "_meta")]
2130        pub meta: Option<Meta>,
2131    }
2132}
2133
2134impl ResumeSessionResponse {
2135    /// Builds [`ResumeSessionResponse`] with the required response fields set. Optional fields start unset or empty.
2136    #[must_use]
2137    pub fn new() -> Self {
2138        Self::default()
2139    }
2140
2141    /// Initial mode state if supported by the Agent
2142    ///
2143    /// See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/session-modes)
2144    #[must_use]
2145    pub fn modes(mut self, modes: impl IntoOption<SessionModeState>) -> Self {
2146        self.modes = modes.into_option();
2147        self
2148    }
2149
2150    /// Initial session configuration options if supported by the Agent.
2151    #[must_use]
2152    pub fn config_options(
2153        mut self,
2154        config_options: impl IntoOption<Vec<SessionConfigOption>>,
2155    ) -> Self {
2156        self.config_options = config_options.into_option();
2157        self
2158    }
2159
2160    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2161    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2162    /// these keys.
2163    ///
2164    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2165    #[must_use]
2166    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
2167        self.meta = meta.into_option();
2168        self
2169    }
2170}
2171
2172// Close session
2173
2174/// Request parameters for closing an active session.
2175///
2176/// If supported, the agent **must** cancel any ongoing work related to the session
2177/// (treat it as if `session/cancel` was called) and then free up any resources
2178/// associated with the session.
2179///
2180/// Only available if the Agent supports the `sessionCapabilities.close` capability.
2181#[serde_as]
2182#[skip_serializing_none]
2183#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
2184#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
2185#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_CLOSE_METHOD_NAME)))]
2186#[serde(rename_all = "camelCase")]
2187#[non_exhaustive]
2188pub struct CloseSessionRequest {
2189    /// The ID of the session to close.
2190    pub session_id: SessionId,
2191    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2192    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2193    /// these keys.
2194    ///
2195    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2196    #[serde_as(deserialize_as = "DefaultOnError")]
2197    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
2198    #[serde(default)]
2199    #[serde(rename = "_meta")]
2200    pub meta: Option<Meta>,
2201}
2202
2203impl CloseSessionRequest {
2204    /// Builds [`CloseSessionRequest`] with the required request fields set. Optional fields start unset or empty.
2205    #[must_use]
2206    pub fn new(session_id: impl Into<SessionId>) -> Self {
2207        Self {
2208            session_id: session_id.into(),
2209            meta: None,
2210        }
2211    }
2212
2213    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2214    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2215    /// these keys.
2216    ///
2217    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2218    #[must_use]
2219    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
2220        self.meta = meta.into_option();
2221        self
2222    }
2223}
2224
2225crate::serde_util::default_on_null! {
2226    /// Response from closing a session.
2227    #[serde_as]
2228    #[skip_serializing_none]
2229    #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
2230    #[derive(Default, Debug, Clone, Serialize, PartialEq, Eq)]
2231    #[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_CLOSE_METHOD_NAME)))]
2232    #[serde(rename_all = "camelCase")]
2233    #[non_exhaustive]
2234    pub struct CloseSessionResponse {
2235        /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2236        /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2237        /// these keys.
2238        ///
2239        /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2240        #[serde_as(deserialize_as = "DefaultOnError")]
2241        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
2242        #[serde(default)]
2243        #[serde(rename = "_meta")]
2244        pub meta: Option<Meta>,
2245    }
2246}
2247
2248impl CloseSessionResponse {
2249    /// Builds [`CloseSessionResponse`] with the required response fields set. Optional fields start unset or empty.
2250    #[must_use]
2251    pub fn new() -> Self {
2252        Self::default()
2253    }
2254
2255    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2256    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2257    /// these keys.
2258    ///
2259    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2260    #[must_use]
2261    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
2262        self.meta = meta.into_option();
2263        self
2264    }
2265}
2266
2267// Session status
2268
2269/// **UNSTABLE**
2270///
2271/// This capability is not part of the spec yet, and may be removed or changed at any point.
2272///
2273/// Request parameters for checking the status of a session.
2274///
2275/// Only available if the Agent supports the `sessionCapabilities.status` capability.
2276///
2277/// `session/status` MUST NOT have side effects. The Agent does not load, resume, create,
2278/// close, or change the session, and does not attach the requesting connection to it.
2279/// A session the Agent does not know gets `-32002` with the requested `sessionId` in `data`.
2280#[cfg(feature = "unstable_session_status")]
2281#[serde_as]
2282#[skip_serializing_none]
2283#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
2284#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
2285#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_STATUS_METHOD_NAME)))]
2286#[serde(rename_all = "camelCase")]
2287#[non_exhaustive]
2288pub struct SessionStatusRequest {
2289    /// The ID of the session to check.
2290    pub session_id: SessionId,
2291    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2292    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2293    /// these keys.
2294    ///
2295    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2296    #[serde_as(deserialize_as = "DefaultOnError")]
2297    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
2298    #[serde(default)]
2299    #[serde(rename = "_meta")]
2300    pub meta: Option<Meta>,
2301}
2302
2303#[cfg(feature = "unstable_session_status")]
2304impl SessionStatusRequest {
2305    /// Builds [`SessionStatusRequest`] with the required request fields set. Optional fields start unset or empty.
2306    #[must_use]
2307    pub fn new(session_id: impl Into<SessionId>) -> Self {
2308        Self {
2309            session_id: session_id.into(),
2310            meta: None,
2311        }
2312    }
2313
2314    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2315    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2316    /// these keys.
2317    ///
2318    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2319    #[must_use]
2320    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
2321        self.meta = meta.into_option();
2322        self
2323    }
2324}
2325
2326/// **UNSTABLE**
2327///
2328/// This capability is not part of the spec yet, and may be removed or changed at any point.
2329///
2330/// Response from checking the status of a session.
2331///
2332/// The result is a snapshot. A session reported `open` may be closed or evicted before
2333/// the Client's next request.
2334#[cfg(feature = "unstable_session_status")]
2335#[serde_as]
2336#[skip_serializing_none]
2337#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
2338#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
2339#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_STATUS_METHOD_NAME)))]
2340#[serde(rename_all = "camelCase")]
2341#[non_exhaustive]
2342pub struct SessionStatusResponse {
2343    /// Whether the Agent has the session in memory.
2344    ///
2345    /// Required. Clients MUST treat a value they do not recognize as `saved`.
2346    pub status: SessionStatus,
2347    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2348    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2349    /// these keys.
2350    ///
2351    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2352    #[serde_as(deserialize_as = "DefaultOnError")]
2353    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
2354    #[serde(default)]
2355    #[serde(rename = "_meta")]
2356    pub meta: Option<Meta>,
2357}
2358
2359#[cfg(feature = "unstable_session_status")]
2360impl SessionStatusResponse {
2361    /// Builds [`SessionStatusResponse`] with the required response fields set. Optional fields start unset or empty.
2362    #[must_use]
2363    pub fn new(status: SessionStatus) -> Self {
2364        Self { status, meta: None }
2365    }
2366
2367    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2368    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2369    /// these keys.
2370    ///
2371    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2372    #[must_use]
2373    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
2374        self.meta = meta.into_option();
2375        self
2376    }
2377}
2378
2379/// **UNSTABLE**
2380///
2381/// This capability is not part of the spec yet, and may be removed or changed at any point.
2382///
2383/// Whether the Agent has a session in memory, as reported by `session/status`.
2384#[cfg(feature = "unstable_session_status")]
2385#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
2386#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
2387#[serde(rename_all = "snake_case")]
2388#[non_exhaustive]
2389pub enum SessionStatus {
2390    /// The Agent has the session in memory, for any connection.
2391    ///
2392    /// This does not mean the requesting connection is attached to it. A Client that did
2393    /// not create or resume the session on its own connection MUST still call
2394    /// `session/load` or `session/resume` before sending `session/prompt` or expecting
2395    /// `session/update` notifications.
2396    Open,
2397    /// The Agent knows the session and can resume it, but does not have it in memory.
2398    ///
2399    /// The Client can call `session/load` or `session/resume` to start it.
2400    Saved,
2401    /// Custom or future session status.
2402    ///
2403    /// Values beginning with `_` are reserved for implementation-specific
2404    /// extensions. Unknown values that do not begin with `_` are reserved for
2405    /// future ACP variants. Clients MUST treat a value they do not recognize as
2406    /// `saved`.
2407    #[serde(untagged)]
2408    Other(String),
2409}
2410
2411/// **UNSTABLE**
2412///
2413/// This capability is not part of the spec yet, and may be removed or changed at any point.
2414///
2415/// Request parameters for `session/options`, which returns the config options a session
2416/// would start with, without creating or resuming a session.
2417///
2418/// Only available if the Agent supports the `sessionCapabilities.options` capability.
2419///
2420/// `session/options` MUST NOT create or resume a session, send `session/update`
2421/// notifications, add an entry to `session/list`, or change an existing session. Agents
2422/// SHOULD NOT connect to MCP servers to answer it. Agents MAY start their runtime to resolve
2423/// the options. The rules above still hold for it.
2424#[cfg(feature = "unstable_session_options")]
2425#[serde_as]
2426#[skip_serializing_none]
2427#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
2428#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
2429#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_OPTIONS_METHOD_NAME)))]
2430#[serde(rename_all = "camelCase")]
2431#[non_exhaustive]
2432pub struct SessionOptionsRequest {
2433    /// The working directory to resolve options for. Must be an absolute path.
2434    pub cwd: PathBuf,
2435    /// Additional workspace roots to resolve options for. Each path MUST be absolute.
2436    ///
2437    /// Optional. Omitted and `null` are equivalent to an empty list.
2438    #[serde_as(deserialize_as = "DefaultOnNull")]
2439    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
2440    #[serde(default, skip_serializing_if = "Vec::is_empty")]
2441    pub additional_directories: Vec<PathBuf>,
2442    /// The session to resolve options for.
2443    ///
2444    /// Optional. Omitted and `null` are equivalent and mean a new session. When present,
2445    /// the Agent returns what `session/load` or `session/resume` with the same `cwd` and
2446    /// `additionalDirectories` would return, with the same `cwd` rules. A session the
2447    /// Agent does not know gets `-32002`.
2448    /// Clients MUST only send this when the Agent supports `session/load` (`loadSession`)
2449    /// or `session/resume` (`sessionCapabilities.resume`).
2450    #[serde(default)]
2451    pub session_id: Option<SessionId>,
2452    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2453    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2454    /// these keys.
2455    ///
2456    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2457    #[serde_as(deserialize_as = "DefaultOnError")]
2458    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
2459    #[serde(default)]
2460    #[serde(rename = "_meta")]
2461    pub meta: Option<Meta>,
2462}
2463
2464#[cfg(feature = "unstable_session_options")]
2465impl SessionOptionsRequest {
2466    /// Builds [`SessionOptionsRequest`] with the required request fields set. Optional fields start unset or empty.
2467    #[must_use]
2468    pub fn new(cwd: impl Into<PathBuf>) -> Self {
2469        Self {
2470            cwd: cwd.into(),
2471            additional_directories: vec![],
2472            session_id: None,
2473            meta: None,
2474        }
2475    }
2476
2477    /// Additional workspace roots to resolve options for. Each path MUST be absolute.
2478    #[must_use]
2479    pub fn additional_directories(mut self, additional_directories: Vec<PathBuf>) -> Self {
2480        self.additional_directories = additional_directories;
2481        self
2482    }
2483
2484    /// The session to resolve options for. Unset means a new session.
2485    #[must_use]
2486    pub fn session_id(mut self, session_id: impl IntoOption<SessionId>) -> Self {
2487        self.session_id = session_id.into_option();
2488        self
2489    }
2490
2491    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2492    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2493    /// these keys.
2494    ///
2495    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2496    #[must_use]
2497    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
2498        self.meta = meta.into_option();
2499        self
2500    }
2501}
2502
2503#[cfg(feature = "unstable_session_options")]
2504crate::serde_util::default_on_null! {
2505    /// **UNSTABLE**
2506    ///
2507    /// This capability is not part of the spec yet, and may be removed or changed at any point.
2508    ///
2509    /// Response from `session/options`.
2510    ///
2511    /// The result is a snapshot. The options a session actually starts with are the ones in
2512    /// the session setup response.
2513    ///
2514    /// Agents only return `type: "boolean"` options when the Client advertises
2515    /// `sessionCapabilities.configOptions.boolean`.
2516    #[serde_as]
2517    #[skip_serializing_none]
2518    #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
2519    #[derive(Default, Debug, Clone, Serialize, PartialEq, Eq)]
2520    #[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_OPTIONS_METHOD_NAME)))]
2521    #[serde(rename_all = "camelCase")]
2522    #[non_exhaustive]
2523    pub struct SessionOptionsResponse {
2524        /// The mode state the session would start with, if the Agent supports modes.
2525        ///
2526        /// See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/session-modes)
2527        #[serde_as(deserialize_as = "DefaultOnError")]
2528        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
2529        #[serde(default)]
2530        pub modes: Option<SessionModeState>,
2531        /// The config options the session would start with, with the same rules as on
2532        /// `NewSessionResponse`.
2533        ///
2534        /// Optional. Omitted, `null`, or empty means no config options are advertised.
2535        #[serde_as(deserialize_as = "DefaultOnError<Option<VecSkipError<_>>>")]
2536        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
2537        #[serde(default)]
2538        pub config_options: Option<Vec<SessionConfigOption>>,
2539        /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2540        /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2541        /// these keys.
2542        ///
2543        /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2544        #[serde_as(deserialize_as = "DefaultOnError")]
2545        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
2546        #[serde(default)]
2547        #[serde(rename = "_meta")]
2548        pub meta: Option<Meta>,
2549    }
2550}
2551
2552#[cfg(feature = "unstable_session_options")]
2553impl SessionOptionsResponse {
2554    /// Builds [`SessionOptionsResponse`] with the required response fields set. Optional fields start unset or empty.
2555    #[must_use]
2556    pub fn new() -> Self {
2557        Self::default()
2558    }
2559
2560    /// The mode state the session would start with, if the Agent supports modes.
2561    ///
2562    /// See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/session-modes)
2563    #[must_use]
2564    pub fn modes(mut self, modes: impl IntoOption<SessionModeState>) -> Self {
2565        self.modes = modes.into_option();
2566        self
2567    }
2568
2569    /// The config options the session would start with.
2570    #[must_use]
2571    pub fn config_options(
2572        mut self,
2573        config_options: impl IntoOption<Vec<SessionConfigOption>>,
2574    ) -> Self {
2575        self.config_options = config_options.into_option();
2576        self
2577    }
2578
2579    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2580    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2581    /// these keys.
2582    ///
2583    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2584    #[must_use]
2585    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
2586        self.meta = meta.into_option();
2587        self
2588    }
2589}
2590
2591/// **UNSTABLE**
2592///
2593/// This capability is not part of the spec yet, and may be removed or changed at any point.
2594///
2595/// An initial value for a config option, sent on session setup requests.
2596///
2597/// Same shape as `session/set_config_option` without `sessionId`. Unlike
2598/// `session/set_config_option`, an unknown `configId`, a `type` that does not match the
2599/// option, or a value that is not allowed is ignored instead of rejected.
2600///
2601/// Clients only send `type: "boolean"` entries when they advertise
2602/// `sessionCapabilities.configOptions.boolean`.
2603#[cfg(feature = "unstable_session_options")]
2604#[serde_as]
2605#[skip_serializing_none]
2606#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
2607#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
2608#[serde(rename_all = "camelCase")]
2609#[non_exhaustive]
2610pub struct InitialSessionConfigOption {
2611    /// The ID of the configuration option to set.
2612    pub config_id: SessionConfigId,
2613    /// The value to set, including a `type` discriminator and the raw `value`.
2614    ///
2615    /// When `type` is absent on the wire, defaults to treating the value as a
2616    /// [`SessionConfigValueId`] for `select` options.
2617    #[serde(flatten)]
2618    pub value: SessionConfigOptionValue,
2619    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2620    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2621    /// these keys.
2622    ///
2623    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2624    #[serde_as(deserialize_as = "DefaultOnError")]
2625    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
2626    #[serde(default)]
2627    #[serde(rename = "_meta")]
2628    pub meta: Option<Meta>,
2629}
2630
2631#[cfg(feature = "unstable_session_options")]
2632impl InitialSessionConfigOption {
2633    /// Builds [`InitialSessionConfigOption`] with the required fields set. Optional fields start unset or empty.
2634    #[must_use]
2635    pub fn new(
2636        config_id: impl Into<SessionConfigId>,
2637        value: impl Into<SessionConfigOptionValue>,
2638    ) -> Self {
2639        Self {
2640            config_id: config_id.into(),
2641            value: value.into(),
2642            meta: None,
2643        }
2644    }
2645
2646    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2647    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2648    /// these keys.
2649    ///
2650    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2651    #[must_use]
2652    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
2653        self.meta = meta.into_option();
2654        self
2655    }
2656}
2657
2658// List sessions
2659
2660crate::serde_util::default_on_null! {
2661    /// Request parameters for listing existing sessions.
2662    ///
2663    /// Only available if the Agent supports the `sessionCapabilities.list` capability.
2664    #[serde_as]
2665    #[skip_serializing_none]
2666    #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
2667    #[derive(Default, Debug, Clone, Serialize, PartialEq, Eq)]
2668    #[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_LIST_METHOD_NAME)))]
2669    #[serde(rename_all = "camelCase")]
2670    #[non_exhaustive]
2671    pub struct ListSessionsRequest {
2672        /// Filter sessions by working directory. Must be an absolute path.
2673        #[serde(default)]
2674        pub cwd: Option<PathBuf>,
2675        /// Opaque cursor token from a previous response's nextCursor field for cursor-based pagination
2676        #[serde(default)]
2677        pub cursor: Option<String>,
2678        /// **UNSTABLE**
2679        ///
2680        /// This capability is not part of the spec yet, and may be removed or changed at any point.
2681        ///
2682        /// Filter sessions by archive state.
2683        ///
2684        /// Optional. Omitted and `null` are equivalent and mean `exclude`. Only send this when
2685        /// the Agent advertises the `sessionCapabilities.archive` capability. The filter combines with `cwd` and
2686        /// applies before pagination. Clients keep the same value when following `nextCursor`.
2687        #[cfg(feature = "unstable_session_archive")]
2688        #[serde(default)]
2689        pub archived: Option<SessionArchiveFilter>,
2690        /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2691        /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2692        /// these keys.
2693        ///
2694        /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2695        #[serde_as(deserialize_as = "DefaultOnError")]
2696        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
2697        #[serde(default)]
2698        #[serde(rename = "_meta")]
2699        pub meta: Option<Meta>,
2700    }
2701}
2702
2703impl ListSessionsRequest {
2704    /// Builds [`ListSessionsRequest`] with the required request fields set. Optional fields start unset or empty.
2705    #[must_use]
2706    pub fn new() -> Self {
2707        Self::default()
2708    }
2709
2710    /// Filter sessions by working directory. Must be an absolute path.
2711    #[must_use]
2712    pub fn cwd(mut self, cwd: impl IntoOption<PathBuf>) -> Self {
2713        self.cwd = cwd.into_option();
2714        self
2715    }
2716
2717    /// Opaque cursor token from a previous response's nextCursor field for cursor-based pagination
2718    #[must_use]
2719    pub fn cursor(mut self, cursor: impl IntoOption<String>) -> Self {
2720        self.cursor = cursor.into_option();
2721        self
2722    }
2723
2724    /// **UNSTABLE**
2725    ///
2726    /// This capability is not part of the spec yet, and may be removed or changed at any point.
2727    ///
2728    /// Filter sessions by archive state.
2729    #[cfg(feature = "unstable_session_archive")]
2730    #[must_use]
2731    pub fn archived(mut self, archived: impl IntoOption<SessionArchiveFilter>) -> Self {
2732        self.archived = archived.into_option();
2733        self
2734    }
2735
2736    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2737    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2738    /// these keys.
2739    ///
2740    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2741    #[must_use]
2742    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
2743        self.meta = meta.into_option();
2744        self
2745    }
2746}
2747
2748/// Response from listing sessions.
2749#[serde_as]
2750#[skip_serializing_none]
2751#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
2752#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
2753#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_LIST_METHOD_NAME)))]
2754#[serde(rename_all = "camelCase")]
2755#[non_exhaustive]
2756pub struct ListSessionsResponse {
2757    /// Array of session information objects
2758    #[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_>>")]
2759    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
2760    pub sessions: Vec<SessionInfo>,
2761    /// Opaque cursor token. If present, pass this in the next request's cursor parameter
2762    /// to fetch the next page. If absent, there are no more results.
2763    #[serde_as(deserialize_as = "DefaultOnError")]
2764    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
2765    #[serde(default)]
2766    pub next_cursor: Option<String>,
2767    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2768    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2769    /// these keys.
2770    ///
2771    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2772    #[serde_as(deserialize_as = "DefaultOnError")]
2773    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
2774    #[serde(default)]
2775    #[serde(rename = "_meta")]
2776    pub meta: Option<Meta>,
2777}
2778
2779impl ListSessionsResponse {
2780    /// Builds [`ListSessionsResponse`] with the required response fields set. Optional fields start unset or empty.
2781    #[must_use]
2782    pub fn new(sessions: Vec<SessionInfo>) -> Self {
2783        Self {
2784            sessions,
2785            next_cursor: None,
2786            meta: None,
2787        }
2788    }
2789
2790    /// Sets or clears the optional `nextCursor` field.
2791    #[must_use]
2792    pub fn next_cursor(mut self, next_cursor: impl IntoOption<String>) -> Self {
2793        self.next_cursor = next_cursor.into_option();
2794        self
2795    }
2796
2797    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2798    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2799    /// these keys.
2800    ///
2801    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2802    #[must_use]
2803    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
2804        self.meta = meta.into_option();
2805        self
2806    }
2807}
2808
2809// Delete session
2810
2811/// Request parameters for deleting an existing session from `session/list`.
2812///
2813/// Only available if the Agent supports the `sessionCapabilities.delete` capability.
2814#[serde_as]
2815#[skip_serializing_none]
2816#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
2817#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
2818#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_DELETE_METHOD_NAME)))]
2819#[serde(rename_all = "camelCase")]
2820#[non_exhaustive]
2821pub struct DeleteSessionRequest {
2822    /// The ID of the session to delete.
2823    pub session_id: SessionId,
2824    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2825    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2826    /// these keys.
2827    ///
2828    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2829    #[serde_as(deserialize_as = "DefaultOnError")]
2830    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
2831    #[serde(default)]
2832    #[serde(rename = "_meta")]
2833    pub meta: Option<Meta>,
2834}
2835
2836impl DeleteSessionRequest {
2837    /// Builds [`DeleteSessionRequest`] with the required request fields set. Optional fields start unset or empty.
2838    #[must_use]
2839    pub fn new(session_id: impl Into<SessionId>) -> Self {
2840        Self {
2841            session_id: session_id.into(),
2842            meta: None,
2843        }
2844    }
2845
2846    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2847    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2848    /// these keys.
2849    ///
2850    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2851    #[must_use]
2852    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
2853        self.meta = meta.into_option();
2854        self
2855    }
2856}
2857
2858crate::serde_util::default_on_null! {
2859    /// Response from deleting a session.
2860    #[serde_as]
2861    #[skip_serializing_none]
2862    #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
2863    #[derive(Default, Debug, Clone, Serialize, PartialEq, Eq)]
2864    #[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_DELETE_METHOD_NAME)))]
2865    #[serde(rename_all = "camelCase")]
2866    #[non_exhaustive]
2867    pub struct DeleteSessionResponse {
2868        /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2869        /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2870        /// these keys.
2871        ///
2872        /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2873        #[serde_as(deserialize_as = "DefaultOnError")]
2874        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
2875        #[serde(default)]
2876        #[serde(rename = "_meta")]
2877        pub meta: Option<Meta>,
2878    }
2879}
2880
2881impl DeleteSessionResponse {
2882    /// Builds [`DeleteSessionResponse`] with the required response fields set. Optional fields start unset or empty.
2883    #[must_use]
2884    pub fn new() -> Self {
2885        Self::default()
2886    }
2887
2888    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2889    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2890    /// these keys.
2891    ///
2892    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2893    #[must_use]
2894    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
2895        self.meta = meta.into_option();
2896        self
2897    }
2898}
2899
2900// Archive session
2901
2902/// **UNSTABLE**
2903///
2904/// This capability is not part of the spec yet, and may be removed or changed at any point.
2905///
2906/// Request parameters for archiving a session.
2907///
2908/// Only available if the Agent supports the `sessionCapabilities.archive` capability.
2909///
2910/// Archiving hides the session from default `session/list` results. It keeps the session ID
2911/// and saved history. If the session is active, the Agent MUST cancel any ongoing work and
2912/// free the session's resources as if `session/close` had been called, then archive it.
2913/// Archiving an archived session succeeds. A session that does not exist gets `-32002`.
2914///
2915#[cfg(feature = "unstable_session_archive")]
2916#[serde_as]
2917#[skip_serializing_none]
2918#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
2919#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
2920#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_ARCHIVE_METHOD_NAME)))]
2921#[serde(rename_all = "camelCase")]
2922#[non_exhaustive]
2923pub struct ArchiveSessionRequest {
2924    /// The ID of the session to archive.
2925    pub session_id: SessionId,
2926    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2927    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2928    /// these keys.
2929    ///
2930    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2931    #[serde_as(deserialize_as = "DefaultOnError")]
2932    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
2933    #[serde(default)]
2934    #[serde(rename = "_meta")]
2935    pub meta: Option<Meta>,
2936}
2937
2938#[cfg(feature = "unstable_session_archive")]
2939impl ArchiveSessionRequest {
2940    /// Builds [`ArchiveSessionRequest`] with the required request fields set. Optional fields start unset or empty.
2941    #[must_use]
2942    pub fn new(session_id: impl Into<SessionId>) -> Self {
2943        Self {
2944            session_id: session_id.into(),
2945            meta: None,
2946        }
2947    }
2948
2949    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2950    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2951    /// these keys.
2952    ///
2953    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2954    #[must_use]
2955    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
2956        self.meta = meta.into_option();
2957        self
2958    }
2959}
2960
2961#[cfg(feature = "unstable_session_archive")]
2962crate::serde_util::default_on_null! {
2963    /// **UNSTABLE**
2964    ///
2965    /// This capability is not part of the spec yet, and may be removed or changed at any point.
2966    ///
2967    /// Response from archiving a session.
2968    #[serde_as]
2969    #[skip_serializing_none]
2970    #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
2971    #[derive(Default, Debug, Clone, Serialize, PartialEq, Eq)]
2972    #[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_ARCHIVE_METHOD_NAME)))]
2973    #[serde(rename_all = "camelCase")]
2974    #[non_exhaustive]
2975    pub struct ArchiveSessionResponse {
2976        /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2977        /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2978        /// these keys.
2979        ///
2980        /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
2981        #[serde_as(deserialize_as = "DefaultOnError")]
2982        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
2983        #[serde(default)]
2984        #[serde(rename = "_meta")]
2985        pub meta: Option<Meta>,
2986    }
2987}
2988
2989#[cfg(feature = "unstable_session_archive")]
2990impl ArchiveSessionResponse {
2991    /// Builds [`ArchiveSessionResponse`] with the required response fields set. Optional fields start unset or empty.
2992    #[must_use]
2993    pub fn new() -> Self {
2994        Self::default()
2995    }
2996
2997    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
2998    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
2999    /// these keys.
3000    ///
3001    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3002    #[must_use]
3003    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
3004        self.meta = meta.into_option();
3005        self
3006    }
3007}
3008
3009/// **UNSTABLE**
3010///
3011/// This capability is not part of the spec yet, and may be removed or changed at any point.
3012///
3013/// Request parameters for unarchiving a session.
3014///
3015/// Only available if the Agent supports the `sessionCapabilities.archive` capability.
3016///
3017/// Unarchiving returns the session to default `session/list` results with the same ID and
3018/// saved history. It never loads or resumes the session. Clients that want to continue an
3019/// archived session SHOULD unarchive it before calling `session/load` or `session/resume`.
3020/// Unarchiving a session that is not archived succeeds. A session that does not exist
3021/// gets `-32002`.
3022///
3023#[cfg(feature = "unstable_session_archive")]
3024#[serde_as]
3025#[skip_serializing_none]
3026#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
3027#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
3028#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_UNARCHIVE_METHOD_NAME)))]
3029#[serde(rename_all = "camelCase")]
3030#[non_exhaustive]
3031pub struct UnarchiveSessionRequest {
3032    /// The ID of the session to unarchive.
3033    pub session_id: SessionId,
3034    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3035    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3036    /// these keys.
3037    ///
3038    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3039    #[serde_as(deserialize_as = "DefaultOnError")]
3040    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
3041    #[serde(default)]
3042    #[serde(rename = "_meta")]
3043    pub meta: Option<Meta>,
3044}
3045
3046#[cfg(feature = "unstable_session_archive")]
3047impl UnarchiveSessionRequest {
3048    /// Builds [`UnarchiveSessionRequest`] with the required request fields set. Optional fields start unset or empty.
3049    #[must_use]
3050    pub fn new(session_id: impl Into<SessionId>) -> Self {
3051        Self {
3052            session_id: session_id.into(),
3053            meta: None,
3054        }
3055    }
3056
3057    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3058    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3059    /// these keys.
3060    ///
3061    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3062    #[must_use]
3063    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
3064        self.meta = meta.into_option();
3065        self
3066    }
3067}
3068
3069#[cfg(feature = "unstable_session_archive")]
3070crate::serde_util::default_on_null! {
3071    /// **UNSTABLE**
3072    ///
3073    /// This capability is not part of the spec yet, and may be removed or changed at any point.
3074    ///
3075    /// Response from unarchiving a session.
3076    #[serde_as]
3077    #[skip_serializing_none]
3078    #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
3079    #[derive(Default, Debug, Clone, Serialize, PartialEq, Eq)]
3080    #[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_UNARCHIVE_METHOD_NAME)))]
3081    #[serde(rename_all = "camelCase")]
3082    #[non_exhaustive]
3083    pub struct UnarchiveSessionResponse {
3084        /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3085        /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3086        /// these keys.
3087        ///
3088        /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3089        #[serde_as(deserialize_as = "DefaultOnError")]
3090        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
3091        #[serde(default)]
3092        #[serde(rename = "_meta")]
3093        pub meta: Option<Meta>,
3094    }
3095}
3096
3097#[cfg(feature = "unstable_session_archive")]
3098impl UnarchiveSessionResponse {
3099    /// Builds [`UnarchiveSessionResponse`] with the required response fields set. Optional fields start unset or empty.
3100    #[must_use]
3101    pub fn new() -> Self {
3102        Self::default()
3103    }
3104
3105    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3106    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3107    /// these keys.
3108    ///
3109    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3110    #[must_use]
3111    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
3112        self.meta = meta.into_option();
3113        self
3114    }
3115}
3116
3117/// **UNSTABLE**
3118///
3119/// This capability is not part of the spec yet, and may be removed or changed at any point.
3120///
3121/// Which sessions `session/list` returns based on their archive state.
3122///
3123/// Unknown values are preserved so they can be stored, proxied, or forwarded. An Agent MUST
3124/// return `-32602` for a value it does not support rather than treating it as `exclude`.
3125#[cfg(feature = "unstable_session_archive")]
3126#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
3127#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
3128#[serde(rename_all = "snake_case")]
3129#[non_exhaustive]
3130pub enum SessionArchiveFilter {
3131    /// Only sessions that are not archived. This is the default.
3132    #[default]
3133    Exclude,
3134    /// Both archived sessions and sessions that are not archived.
3135    Include,
3136    /// Only archived sessions.
3137    Only,
3138    /// Custom or future archive filter.
3139    ///
3140    /// Values beginning with `_` are reserved for implementation-specific
3141    /// extensions. Unknown values that do not begin with `_` are reserved for
3142    /// future ACP variants.
3143    #[serde(untagged)]
3144    Other(String),
3145}
3146
3147/// Information about a session returned by session/list
3148#[serde_as]
3149#[skip_serializing_none]
3150#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
3151#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
3152#[serde(rename_all = "camelCase")]
3153#[non_exhaustive]
3154pub struct SessionInfo {
3155    /// Unique identifier for the session
3156    pub session_id: SessionId,
3157    /// The working directory for this session. Must be an absolute path.
3158    pub cwd: PathBuf,
3159    /// Additional workspace roots reported for this session. Each path MUST be absolute.
3160    ///
3161    /// When present, this is the complete ordered additional-root list reported
3162    /// by the Agent. Omitted and empty values are equivalent: the response
3163    /// reports no additional roots.
3164    #[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_>>")]
3165    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
3166    #[serde(default, skip_serializing_if = "Vec::is_empty")]
3167    pub additional_directories: Vec<PathBuf>,
3168
3169    /// Human-readable title for the session
3170    #[serde_as(deserialize_as = "DefaultOnError")]
3171    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
3172    #[serde(default)]
3173    pub title: Option<String>,
3174    /// ISO 8601 timestamp of last activity
3175    #[serde_as(deserialize_as = "DefaultOnError")]
3176    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
3177    #[serde(default)]
3178    pub updated_at: Option<String>,
3179    /// **UNSTABLE**
3180    ///
3181    /// This capability is not part of the spec yet, and may be removed or changed at any point.
3182    ///
3183    /// Whether the session is archived.
3184    ///
3185    /// Optional. Omitted and `null` are equivalent and mean the archive state is not reported.
3186    /// Agents that advertise the `sessionCapabilities.archive` capability MUST include it on every listed session.
3187    #[cfg(feature = "unstable_session_archive")]
3188    #[serde_as(deserialize_as = "DefaultOnError")]
3189    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
3190    #[serde(default)]
3191    pub archived: Option<bool>,
3192    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3193    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3194    /// these keys.
3195    ///
3196    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3197    #[serde_as(deserialize_as = "DefaultOnError")]
3198    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
3199    #[serde(default)]
3200    #[serde(rename = "_meta")]
3201    pub meta: Option<Meta>,
3202}
3203
3204impl SessionInfo {
3205    /// Builds [`SessionInfo`] with the required fields set. Optional fields start unset or empty.
3206    #[must_use]
3207    pub fn new(session_id: impl Into<SessionId>, cwd: impl Into<PathBuf>) -> Self {
3208        Self {
3209            session_id: session_id.into(),
3210            cwd: cwd.into(),
3211            additional_directories: vec![],
3212            title: None,
3213            updated_at: None,
3214            #[cfg(feature = "unstable_session_archive")]
3215            archived: None,
3216            meta: None,
3217        }
3218    }
3219
3220    /// Additional workspace roots reported for this session. Each path MUST be absolute.
3221    #[must_use]
3222    pub fn additional_directories(mut self, additional_directories: Vec<PathBuf>) -> Self {
3223        self.additional_directories = additional_directories;
3224        self
3225    }
3226
3227    /// Human-readable title for the session
3228    #[must_use]
3229    pub fn title(mut self, title: impl IntoOption<String>) -> Self {
3230        self.title = title.into_option();
3231        self
3232    }
3233
3234    /// ISO 8601 timestamp of last activity
3235    #[must_use]
3236    pub fn updated_at(mut self, updated_at: impl IntoOption<String>) -> Self {
3237        self.updated_at = updated_at.into_option();
3238        self
3239    }
3240
3241    /// **UNSTABLE**
3242    ///
3243    /// This capability is not part of the spec yet, and may be removed or changed at any point.
3244    ///
3245    /// Whether the session is archived.
3246    #[cfg(feature = "unstable_session_archive")]
3247    #[must_use]
3248    pub fn archived(mut self, archived: impl IntoOption<bool>) -> Self {
3249        self.archived = archived.into_option();
3250        self
3251    }
3252
3253    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3254    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3255    /// these keys.
3256    ///
3257    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3258    #[must_use]
3259    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
3260        self.meta = meta.into_option();
3261        self
3262    }
3263}
3264
3265// Set session title
3266
3267/// **UNSTABLE**
3268///
3269/// This capability is not part of the spec yet, and may be removed or changed at any point.
3270///
3271/// Request parameters for setting the title of a session.
3272///
3273/// Only available if the Agent supports the `sessionCapabilities.title` capability.
3274///
3275/// The session does not need to be active on the connection. Any session the Agent would
3276/// return from `session/list` can be retitled. A session that does not exist gets `-32002`.
3277///
3278/// The Agent responds only after it has stored the title. After a successful response, the
3279/// Agent SHOULD NOT replace the title with one it generates automatically.
3280#[cfg(feature = "unstable_session_set_title")]
3281#[serde_as]
3282#[skip_serializing_none]
3283#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
3284#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
3285#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_SET_TITLE_METHOD_NAME)))]
3286#[serde(rename_all = "camelCase")]
3287#[non_exhaustive]
3288pub struct SetSessionTitleRequest {
3289    /// The ID of the session to retitle.
3290    pub session_id: SessionId,
3291    /// The new title for the session.
3292    ///
3293    /// Required and non-null. Omission and explicit `null` are both invalid. The Agent MAY
3294    /// normalize the title before storing it, for example by trimming whitespace or
3295    /// truncating it. The Agent rejects a title that fails its validation, including one
3296    /// that is empty after normalization, with `-32602`.
3297    pub title: String,
3298    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3299    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3300    /// these keys.
3301    ///
3302    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3303    #[serde_as(deserialize_as = "DefaultOnError")]
3304    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
3305    #[serde(default)]
3306    #[serde(rename = "_meta")]
3307    pub meta: Option<Meta>,
3308}
3309
3310#[cfg(feature = "unstable_session_set_title")]
3311impl SetSessionTitleRequest {
3312    /// Builds [`SetSessionTitleRequest`] with the required request fields set. Optional fields start unset or empty.
3313    #[must_use]
3314    pub fn new(session_id: impl Into<SessionId>, title: impl Into<String>) -> Self {
3315        Self {
3316            session_id: session_id.into(),
3317            title: title.into(),
3318            meta: None,
3319        }
3320    }
3321
3322    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3323    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3324    /// these keys.
3325    ///
3326    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3327    #[must_use]
3328    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
3329        self.meta = meta.into_option();
3330        self
3331    }
3332}
3333
3334/// **UNSTABLE**
3335///
3336/// This capability is not part of the spec yet, and may be removed or changed at any point.
3337///
3338/// Response from setting the title of a session.
3339#[cfg(feature = "unstable_session_set_title")]
3340#[serde_as]
3341#[skip_serializing_none]
3342#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
3343#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
3344#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_SET_TITLE_METHOD_NAME)))]
3345#[serde(rename_all = "camelCase")]
3346#[non_exhaustive]
3347pub struct SetSessionTitleResponse {
3348    /// The title the Agent stored.
3349    ///
3350    /// This differs from the requested title if the Agent normalized it. Clients SHOULD
3351    /// display this value rather than the one they sent.
3352    pub title: String,
3353    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3354    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3355    /// these keys.
3356    ///
3357    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3358    #[serde_as(deserialize_as = "DefaultOnError")]
3359    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
3360    #[serde(default)]
3361    #[serde(rename = "_meta")]
3362    pub meta: Option<Meta>,
3363}
3364
3365#[cfg(feature = "unstable_session_set_title")]
3366impl SetSessionTitleResponse {
3367    /// Builds [`SetSessionTitleResponse`] with the required response fields set. Optional fields start unset or empty.
3368    #[must_use]
3369    pub fn new(title: impl Into<String>) -> Self {
3370        Self {
3371            title: title.into(),
3372            meta: None,
3373        }
3374    }
3375
3376    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3377    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3378    /// these keys.
3379    ///
3380    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3381    #[must_use]
3382    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
3383        self.meta = meta.into_option();
3384        self
3385    }
3386}
3387
3388// Session modes
3389
3390/// The set of modes and the one currently active.
3391#[serde_as]
3392#[skip_serializing_none]
3393#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
3394#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
3395#[serde(rename_all = "camelCase")]
3396#[non_exhaustive]
3397pub struct SessionModeState {
3398    /// The current mode the Agent is in.
3399    pub current_mode_id: SessionModeId,
3400    /// The set of modes that the Agent can operate in
3401    #[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_>>")]
3402    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
3403    pub available_modes: Vec<SessionMode>,
3404    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3405    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3406    /// these keys.
3407    ///
3408    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3409    #[serde_as(deserialize_as = "DefaultOnError")]
3410    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
3411    #[serde(default)]
3412    #[serde(rename = "_meta")]
3413    pub meta: Option<Meta>,
3414}
3415
3416impl SessionModeState {
3417    /// Builds [`SessionModeState`] with the required fields set. Optional fields start unset or empty.
3418    #[must_use]
3419    pub fn new(
3420        current_mode_id: impl Into<SessionModeId>,
3421        available_modes: Vec<SessionMode>,
3422    ) -> Self {
3423        Self {
3424            current_mode_id: current_mode_id.into(),
3425            available_modes,
3426            meta: None,
3427        }
3428    }
3429
3430    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3431    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3432    /// these keys.
3433    ///
3434    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3435    #[must_use]
3436    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
3437        self.meta = meta.into_option();
3438        self
3439    }
3440}
3441
3442/// A mode the agent can operate in.
3443///
3444/// See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/session-modes)
3445#[serde_as]
3446#[skip_serializing_none]
3447#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
3448#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
3449#[serde(rename_all = "camelCase")]
3450#[non_exhaustive]
3451pub struct SessionMode {
3452    /// Stable identifier used to refer to this protocol object in later messages.
3453    pub id: SessionModeId,
3454    /// Human-readable name shown for this protocol object.
3455    pub name: String,
3456    /// Optional human-readable details shown with this protocol object.
3457    #[serde_as(deserialize_as = "DefaultOnError")]
3458    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
3459    #[serde(default)]
3460    pub description: Option<String>,
3461    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3462    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3463    /// these keys.
3464    ///
3465    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3466    #[serde_as(deserialize_as = "DefaultOnError")]
3467    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
3468    #[serde(default)]
3469    #[serde(rename = "_meta")]
3470    pub meta: Option<Meta>,
3471}
3472
3473impl SessionMode {
3474    /// Builds [`SessionMode`] with the required fields set. Optional fields start unset or empty.
3475    #[must_use]
3476    pub fn new(id: impl Into<SessionModeId>, name: impl Into<String>) -> Self {
3477        Self {
3478            id: id.into(),
3479            name: name.into(),
3480            description: None,
3481            meta: None,
3482        }
3483    }
3484
3485    /// Sets or clears the optional `description` field.
3486    #[must_use]
3487    pub fn description(mut self, description: impl IntoOption<String>) -> Self {
3488        self.description = description.into_option();
3489        self
3490    }
3491
3492    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3493    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3494    /// these keys.
3495    ///
3496    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3497    #[must_use]
3498    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
3499        self.meta = meta.into_option();
3500        self
3501    }
3502}
3503
3504/// Unique identifier for a Session Mode.
3505#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
3506#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, From, Display)]
3507#[serde(transparent)]
3508#[from(Arc<str>, String, &'static str)]
3509#[non_exhaustive]
3510pub struct SessionModeId(pub Arc<str>);
3511
3512impl SessionModeId {
3513    /// Wraps a protocol string as a typed [`SessionModeId`].
3514    #[must_use]
3515    pub fn new(id: impl Into<Arc<str>>) -> Self {
3516        Self(id.into())
3517    }
3518}
3519
3520/// Request parameters for setting a session mode.
3521#[serde_as]
3522#[skip_serializing_none]
3523#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
3524#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
3525#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_SET_MODE_METHOD_NAME)))]
3526#[serde(rename_all = "camelCase")]
3527#[non_exhaustive]
3528pub struct SetSessionModeRequest {
3529    /// The ID of the session to set the mode for.
3530    pub session_id: SessionId,
3531    /// The ID of the mode to set.
3532    pub mode_id: SessionModeId,
3533    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3534    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3535    /// these keys.
3536    ///
3537    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3538    #[serde_as(deserialize_as = "DefaultOnError")]
3539    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
3540    #[serde(default)]
3541    #[serde(rename = "_meta")]
3542    pub meta: Option<Meta>,
3543}
3544
3545impl SetSessionModeRequest {
3546    /// Builds [`SetSessionModeRequest`] with the required request fields set. Optional fields start unset or empty.
3547    #[must_use]
3548    pub fn new(session_id: impl Into<SessionId>, mode_id: impl Into<SessionModeId>) -> Self {
3549        Self {
3550            session_id: session_id.into(),
3551            mode_id: mode_id.into(),
3552            meta: None,
3553        }
3554    }
3555
3556    /// Sets or clears ACP `_meta` extension metadata.
3557    #[must_use]
3558    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
3559        self.meta = meta.into_option();
3560        self
3561    }
3562}
3563
3564crate::serde_util::default_on_null! {
3565    /// Response to `session/set_mode` method.
3566    #[serde_as]
3567    #[skip_serializing_none]
3568    #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
3569    #[derive(Default, Debug, Clone, Serialize, PartialEq, Eq)]
3570    #[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_SET_MODE_METHOD_NAME)))]
3571    #[serde(rename_all = "camelCase")]
3572    #[non_exhaustive]
3573    pub struct SetSessionModeResponse {
3574        /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3575        /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3576        /// these keys.
3577        ///
3578        /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3579        #[serde_as(deserialize_as = "DefaultOnError")]
3580        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
3581        #[serde(default)]
3582        #[serde(rename = "_meta")]
3583        pub meta: Option<Meta>,
3584    }
3585}
3586
3587impl SetSessionModeResponse {
3588    /// Builds [`SetSessionModeResponse`] with the required response fields set. Optional fields start unset or empty.
3589    #[must_use]
3590    pub fn new() -> Self {
3591        Self::default()
3592    }
3593
3594    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3595    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3596    /// these keys.
3597    ///
3598    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3599    #[must_use]
3600    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
3601        self.meta = meta.into_option();
3602        self
3603    }
3604}
3605
3606// Session config options
3607
3608/// Unique identifier for a session configuration option.
3609#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
3610#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, From, Display)]
3611#[serde(transparent)]
3612#[from(Arc<str>, String, &'static str)]
3613#[non_exhaustive]
3614pub struct SessionConfigId(pub Arc<str>);
3615
3616impl SessionConfigId {
3617    /// Wraps a protocol string as a typed [`SessionConfigId`].
3618    #[must_use]
3619    pub fn new(id: impl Into<Arc<str>>) -> Self {
3620        Self(id.into())
3621    }
3622}
3623
3624/// Unique identifier for a session configuration option value.
3625#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
3626#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, From, Display)]
3627#[serde(transparent)]
3628#[from(Arc<str>, String, &'static str)]
3629#[non_exhaustive]
3630pub struct SessionConfigValueId(pub Arc<str>);
3631
3632impl SessionConfigValueId {
3633    /// Wraps a protocol string as a typed [`SessionConfigValueId`].
3634    #[must_use]
3635    pub fn new(id: impl Into<Arc<str>>) -> Self {
3636        Self(id.into())
3637    }
3638}
3639
3640/// Unique identifier for a session configuration option value group.
3641#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
3642#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, From, Display)]
3643#[serde(transparent)]
3644#[from(Arc<str>, String, &'static str)]
3645#[non_exhaustive]
3646pub struct SessionConfigGroupId(pub Arc<str>);
3647
3648impl SessionConfigGroupId {
3649    /// Wraps a protocol string as a typed [`SessionConfigGroupId`].
3650    #[must_use]
3651    pub fn new(id: impl Into<Arc<str>>) -> Self {
3652        Self(id.into())
3653    }
3654}
3655
3656/// A possible value for a session configuration option.
3657#[serde_as]
3658#[skip_serializing_none]
3659#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
3660#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
3661#[serde(rename_all = "camelCase")]
3662#[non_exhaustive]
3663pub struct SessionConfigSelectOption {
3664    /// Unique identifier for this option value.
3665    pub value: SessionConfigValueId,
3666    /// Human-readable label for this option value.
3667    pub name: String,
3668    /// Optional description for this option value.
3669    #[serde_as(deserialize_as = "DefaultOnError")]
3670    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
3671    #[serde(default)]
3672    pub description: Option<String>,
3673    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3674    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3675    /// these keys.
3676    ///
3677    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3678    #[serde_as(deserialize_as = "DefaultOnError")]
3679    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
3680    #[serde(default)]
3681    #[serde(rename = "_meta")]
3682    pub meta: Option<Meta>,
3683}
3684
3685impl SessionConfigSelectOption {
3686    /// Builds [`SessionConfigSelectOption`] with the required fields set. Optional fields start unset or empty.
3687    #[must_use]
3688    pub fn new(value: impl Into<SessionConfigValueId>, name: impl Into<String>) -> Self {
3689        Self {
3690            value: value.into(),
3691            name: name.into(),
3692            description: None,
3693            meta: None,
3694        }
3695    }
3696
3697    /// Sets or clears the optional `description` field.
3698    #[must_use]
3699    pub fn description(mut self, description: impl IntoOption<String>) -> Self {
3700        self.description = description.into_option();
3701        self
3702    }
3703
3704    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3705    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3706    /// these keys.
3707    ///
3708    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3709    #[must_use]
3710    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
3711        self.meta = meta.into_option();
3712        self
3713    }
3714}
3715
3716/// A group of possible values for a session configuration option.
3717#[serde_as]
3718#[skip_serializing_none]
3719#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
3720#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
3721#[serde(rename_all = "camelCase")]
3722#[non_exhaustive]
3723pub struct SessionConfigSelectGroup {
3724    /// Unique identifier for this group.
3725    pub group: SessionConfigGroupId,
3726    /// Human-readable label for this group.
3727    pub name: String,
3728    /// The set of option values in this group.
3729    #[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_>>")]
3730    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
3731    pub options: Vec<SessionConfigSelectOption>,
3732    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3733    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3734    /// these keys.
3735    ///
3736    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3737    #[serde_as(deserialize_as = "DefaultOnError")]
3738    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
3739    #[serde(default)]
3740    #[serde(rename = "_meta")]
3741    pub meta: Option<Meta>,
3742}
3743
3744impl SessionConfigSelectGroup {
3745    /// Builds [`SessionConfigSelectGroup`] with the required fields set. Optional fields start unset or empty.
3746    #[must_use]
3747    pub fn new(
3748        group: impl Into<SessionConfigGroupId>,
3749        name: impl Into<String>,
3750        options: Vec<SessionConfigSelectOption>,
3751    ) -> Self {
3752        Self {
3753            group: group.into(),
3754            name: name.into(),
3755            options,
3756            meta: None,
3757        }
3758    }
3759
3760    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3761    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3762    /// these keys.
3763    ///
3764    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3765    #[must_use]
3766    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
3767        self.meta = meta.into_option();
3768        self
3769    }
3770}
3771
3772/// Possible values for a session configuration option.
3773#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
3774#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
3775#[serde(untagged)]
3776#[non_exhaustive]
3777pub enum SessionConfigSelectOptions {
3778    /// A flat list of options with no grouping.
3779    Ungrouped(Vec<SessionConfigSelectOption>),
3780    /// A list of options grouped under headers.
3781    Grouped(Vec<SessionConfigSelectGroup>),
3782}
3783
3784impl From<Vec<SessionConfigSelectOption>> for SessionConfigSelectOptions {
3785    fn from(options: Vec<SessionConfigSelectOption>) -> Self {
3786        SessionConfigSelectOptions::Ungrouped(options)
3787    }
3788}
3789
3790impl From<Vec<SessionConfigSelectGroup>> for SessionConfigSelectOptions {
3791    fn from(groups: Vec<SessionConfigSelectGroup>) -> Self {
3792        SessionConfigSelectOptions::Grouped(groups)
3793    }
3794}
3795
3796/// A single-value selector (dropdown) session configuration option payload.
3797#[skip_serializing_none]
3798#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
3799#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
3800#[serde(rename_all = "camelCase")]
3801#[non_exhaustive]
3802pub struct SessionConfigSelect {
3803    /// The currently selected value.
3804    pub current_value: SessionConfigValueId,
3805    /// The set of selectable options.
3806    pub options: SessionConfigSelectOptions,
3807}
3808
3809impl SessionConfigSelect {
3810    /// Builds [`SessionConfigSelect`] with the required fields set. Optional fields start unset or empty.
3811    #[must_use]
3812    pub fn new(
3813        current_value: impl Into<SessionConfigValueId>,
3814        options: impl Into<SessionConfigSelectOptions>,
3815    ) -> Self {
3816        Self {
3817            current_value: current_value.into(),
3818            options: options.into(),
3819        }
3820    }
3821}
3822
3823/// A boolean on/off toggle session configuration option payload.
3824#[skip_serializing_none]
3825#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
3826#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
3827#[serde(rename_all = "camelCase")]
3828#[non_exhaustive]
3829pub struct SessionConfigBoolean {
3830    /// The current value of the boolean option.
3831    pub current_value: bool,
3832}
3833
3834impl SessionConfigBoolean {
3835    /// Builds [`SessionConfigBoolean`] with the required fields set. Optional fields start unset or empty.
3836    #[must_use]
3837    pub fn new(current_value: bool) -> Self {
3838        Self { current_value }
3839    }
3840}
3841
3842/// Semantic category for a session configuration option.
3843///
3844/// This is intended to help Clients distinguish broadly common selectors (e.g. model selector vs
3845/// session mode selector vs thought/reasoning level) for UX purposes (keyboard shortcuts, icons,
3846/// placement). It MUST NOT be required for correctness. Clients MUST handle missing or unknown
3847/// categories gracefully.
3848///
3849/// Category names beginning with `_` are free for custom use, like other ACP extension methods.
3850/// Category names that do not begin with `_` are reserved for the ACP spec.
3851#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
3852#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
3853#[serde(rename_all = "snake_case")]
3854#[non_exhaustive]
3855pub enum SessionConfigOptionCategory {
3856    /// Session mode selector.
3857    Mode,
3858    /// Model selector.
3859    Model,
3860    /// Model-related configuration parameter.
3861    ModelConfig,
3862    /// **UNSTABLE**
3863    ///
3864    /// This capability is not part of the spec yet, and may be removed or changed at any point.
3865    ///
3866    /// Response speed selector, such as a fast mode toggle.
3867    #[cfg(feature = "unstable_speed_config_category")]
3868    Speed,
3869    /// Thought/reasoning level selector.
3870    ThoughtLevel,
3871    /// Unknown / uncategorized selector.
3872    #[serde(untagged)]
3873    Other(String),
3874}
3875
3876/// Type-specific session configuration option payload.
3877#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
3878#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
3879#[serde(tag = "type", rename_all = "snake_case")]
3880#[cfg_attr(feature = "schemars", schemars(extend("discriminator" = {"propertyName": "type"})))]
3881#[non_exhaustive]
3882pub enum SessionConfigKind {
3883    /// Single-value selector (dropdown).
3884    Select(SessionConfigSelect),
3885    /// Boolean on/off toggle.
3886    Boolean(SessionConfigBoolean),
3887}
3888
3889/// A session configuration option selector and its current state.
3890#[serde_as]
3891#[skip_serializing_none]
3892#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
3893#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
3894#[serde(rename_all = "camelCase")]
3895#[non_exhaustive]
3896pub struct SessionConfigOption {
3897    /// Unique identifier for the configuration option.
3898    pub id: SessionConfigId,
3899    /// Human-readable label for the option.
3900    pub name: String,
3901    /// Optional description for the Client to display to the user.
3902    #[serde_as(deserialize_as = "DefaultOnError")]
3903    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
3904    #[serde(default)]
3905    pub description: Option<String>,
3906    /// Optional semantic category for this option (UX only).
3907    #[serde_as(deserialize_as = "DefaultOnError")]
3908    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
3909    #[serde(default)]
3910    pub category: Option<SessionConfigOptionCategory>,
3911    /// Type-specific fields for this configuration option.
3912    #[serde(flatten)]
3913    pub kind: SessionConfigKind,
3914    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3915    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3916    /// these keys.
3917    ///
3918    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3919    #[serde_as(deserialize_as = "DefaultOnError")]
3920    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
3921    #[serde(default)]
3922    #[serde(rename = "_meta")]
3923    pub meta: Option<Meta>,
3924}
3925
3926impl SessionConfigOption {
3927    /// Builds [`SessionConfigOption`] with the required fields set. Optional fields start unset or empty.
3928    #[must_use]
3929    pub fn new(
3930        id: impl Into<SessionConfigId>,
3931        name: impl Into<String>,
3932        kind: SessionConfigKind,
3933    ) -> Self {
3934        Self {
3935            id: id.into(),
3936            name: name.into(),
3937            description: None,
3938            category: None,
3939            kind,
3940            meta: None,
3941        }
3942    }
3943
3944    /// Builds a select-style session configuration option with its current value and choices.
3945    #[must_use]
3946    pub fn select(
3947        id: impl Into<SessionConfigId>,
3948        name: impl Into<String>,
3949        current_value: impl Into<SessionConfigValueId>,
3950        options: impl Into<SessionConfigSelectOptions>,
3951    ) -> Self {
3952        Self::new(
3953            id,
3954            name,
3955            SessionConfigKind::Select(SessionConfigSelect::new(current_value, options)),
3956        )
3957    }
3958
3959    /// Builds a boolean-style session configuration option with its current value.
3960    #[must_use]
3961    pub fn boolean(
3962        id: impl Into<SessionConfigId>,
3963        name: impl Into<String>,
3964        current_value: bool,
3965    ) -> Self {
3966        Self::new(
3967            id,
3968            name,
3969            SessionConfigKind::Boolean(SessionConfigBoolean::new(current_value)),
3970        )
3971    }
3972
3973    /// Sets or clears the optional `description` field.
3974    #[must_use]
3975    pub fn description(mut self, description: impl IntoOption<String>) -> Self {
3976        self.description = description.into_option();
3977        self
3978    }
3979
3980    /// Sets or clears the optional `category` field.
3981    #[must_use]
3982    pub fn category(mut self, category: impl IntoOption<SessionConfigOptionCategory>) -> Self {
3983        self.category = category.into_option();
3984        self
3985    }
3986
3987    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
3988    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
3989    /// these keys.
3990    ///
3991    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
3992    #[must_use]
3993    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
3994        self.meta = meta.into_option();
3995        self
3996    }
3997}
3998
3999/// The value to set for a session configuration option.
4000///
4001/// The `type` field acts as the discriminator in the serialized JSON form.
4002/// When no `type` is present, the value is treated as a [`SessionConfigValueId`]
4003/// via the [`ValueId`](Self::ValueId) fallback variant.
4004///
4005/// The `type` discriminator describes the *shape* of the value, not the option
4006/// kind. For example every option kind that picks from a list of ids
4007/// (`select`, `radio`, …) would use [`ValueId`](Self::ValueId), while a
4008/// future freeform text option would get its own variant.
4009#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
4010#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
4011#[serde(tag = "type", rename_all = "snake_case")]
4012#[non_exhaustive]
4013pub enum SessionConfigOptionValue {
4014    /// A boolean value (`type: "boolean"`).
4015    Boolean {
4016        /// The boolean value.
4017        value: bool,
4018    },
4019    /// A `SessionConfigValueId` string value.
4020    ///
4021    /// This is the default when `type` is absent on the wire. Unknown `type`
4022    /// values with string payloads also gracefully deserialize into this
4023    /// variant.
4024    #[serde(untagged)]
4025    ValueId {
4026        /// The value ID.
4027        value: SessionConfigValueId,
4028    },
4029}
4030
4031impl SessionConfigOptionValue {
4032    /// Create a value-id option value (used by `select` and other id-based option types).
4033    #[must_use]
4034    pub fn value_id(id: impl Into<SessionConfigValueId>) -> Self {
4035        Self::ValueId { value: id.into() }
4036    }
4037
4038    /// Create a boolean option value.
4039    #[must_use]
4040    pub fn boolean(val: bool) -> Self {
4041        Self::Boolean { value: val }
4042    }
4043
4044    /// Return the inner [`SessionConfigValueId`] if this is a
4045    /// [`ValueId`](Self::ValueId) value.
4046    #[must_use]
4047    pub fn as_value_id(&self) -> Option<&SessionConfigValueId> {
4048        match self {
4049            Self::ValueId { value } => Some(value),
4050            _ => None,
4051        }
4052    }
4053
4054    /// Return the inner [`bool`] if this is a [`Boolean`](Self::Boolean) value.
4055    #[must_use]
4056    pub fn as_bool(&self) -> Option<bool> {
4057        match self {
4058            Self::Boolean { value } => Some(*value),
4059            _ => None,
4060        }
4061    }
4062}
4063
4064impl From<SessionConfigValueId> for SessionConfigOptionValue {
4065    fn from(value: SessionConfigValueId) -> Self {
4066        Self::ValueId { value }
4067    }
4068}
4069
4070impl From<bool> for SessionConfigOptionValue {
4071    fn from(value: bool) -> Self {
4072        Self::Boolean { value }
4073    }
4074}
4075
4076impl From<&str> for SessionConfigOptionValue {
4077    fn from(value: &str) -> Self {
4078        Self::ValueId {
4079            value: SessionConfigValueId::new(value),
4080        }
4081    }
4082}
4083
4084/// Request parameters for setting a session configuration option.
4085#[serde_as]
4086#[skip_serializing_none]
4087#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
4088#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
4089#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_SET_CONFIG_OPTION_METHOD_NAME)))]
4090#[serde(rename_all = "camelCase")]
4091#[non_exhaustive]
4092pub struct SetSessionConfigOptionRequest {
4093    /// The ID of the session to set the configuration option for.
4094    pub session_id: SessionId,
4095    /// The ID of the configuration option to set.
4096    pub config_id: SessionConfigId,
4097    /// The value to set, including a `type` discriminator and the raw `value`.
4098    ///
4099    /// When `type` is absent on the wire, defaults to treating the value as a
4100    /// [`SessionConfigValueId`] for `select` options.
4101    #[serde(flatten)]
4102    pub value: SessionConfigOptionValue,
4103    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4104    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4105    /// these keys.
4106    ///
4107    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4108    #[serde_as(deserialize_as = "DefaultOnError")]
4109    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
4110    #[serde(default)]
4111    #[serde(rename = "_meta")]
4112    pub meta: Option<Meta>,
4113}
4114
4115impl SetSessionConfigOptionRequest {
4116    /// Builds [`SetSessionConfigOptionRequest`] with the required request fields set. Optional fields start unset or empty.
4117    #[must_use]
4118    pub fn new(
4119        session_id: impl Into<SessionId>,
4120        config_id: impl Into<SessionConfigId>,
4121        value: impl Into<SessionConfigOptionValue>,
4122    ) -> Self {
4123        Self {
4124            session_id: session_id.into(),
4125            config_id: config_id.into(),
4126            value: value.into(),
4127            meta: None,
4128        }
4129    }
4130
4131    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4132    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4133    /// these keys.
4134    ///
4135    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4136    #[must_use]
4137    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
4138        self.meta = meta.into_option();
4139        self
4140    }
4141}
4142
4143/// Response to `session/set_config_option` method.
4144#[serde_as]
4145#[skip_serializing_none]
4146#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
4147#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
4148#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_SET_CONFIG_OPTION_METHOD_NAME)))]
4149#[serde(rename_all = "camelCase")]
4150#[non_exhaustive]
4151pub struct SetSessionConfigOptionResponse {
4152    /// The full set of configuration options and their current values.
4153    #[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_>>")]
4154    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
4155    pub config_options: Vec<SessionConfigOption>,
4156    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4157    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4158    /// these keys.
4159    ///
4160    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4161    #[serde_as(deserialize_as = "DefaultOnError")]
4162    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
4163    #[serde(default)]
4164    #[serde(rename = "_meta")]
4165    pub meta: Option<Meta>,
4166}
4167
4168impl SetSessionConfigOptionResponse {
4169    /// Builds [`SetSessionConfigOptionResponse`] with the required response fields set. Optional fields start unset or empty.
4170    #[must_use]
4171    pub fn new(config_options: Vec<SessionConfigOption>) -> Self {
4172        Self {
4173            config_options,
4174            meta: None,
4175        }
4176    }
4177
4178    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4179    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4180    /// these keys.
4181    ///
4182    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4183    #[must_use]
4184    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
4185        self.meta = meta.into_option();
4186        self
4187    }
4188}
4189
4190// MCP
4191
4192/// Configuration for connecting to an MCP (Model Context Protocol) server.
4193///
4194/// MCP servers provide tools and context that the agent can use when
4195/// processing prompts.
4196///
4197/// See protocol docs: [MCP Servers](https://agentclientprotocol.com/protocol/v1/session-setup#mcp-servers)
4198#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
4199#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
4200#[serde(tag = "type", rename_all = "snake_case")]
4201#[non_exhaustive]
4202pub enum McpServer {
4203    /// HTTP transport configuration
4204    ///
4205    /// Only available when the Agent capabilities indicate `mcp_capabilities.http` is `true`.
4206    Http(McpServerHttp),
4207    /// SSE transport configuration
4208    ///
4209    /// Only available when the Agent capabilities indicate `mcp_capabilities.sse` is `true`.
4210    Sse(McpServerSse),
4211    /// **UNSTABLE**
4212    ///
4213    /// This capability is not part of the spec yet, and may be removed or changed at any point.
4214    ///
4215    /// ACP transport configuration
4216    ///
4217    /// Only available when the Agent capabilities indicate `mcp_capabilities.acp` is `true`.
4218    /// The MCP server is provided by an ACP component and communicates over the ACP channel.
4219    #[cfg(feature = "unstable_mcp_over_acp")]
4220    Acp(McpServerAcp),
4221    /// Stdio transport configuration
4222    ///
4223    /// All Agents MUST support this transport.
4224    #[serde(untagged)]
4225    Stdio(McpServerStdio),
4226}
4227
4228/// HTTP transport configuration for MCP.
4229#[serde_as]
4230#[skip_serializing_none]
4231#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
4232#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
4233#[serde(rename_all = "camelCase")]
4234#[non_exhaustive]
4235pub struct McpServerHttp {
4236    /// Human-readable name identifying this MCP server.
4237    pub name: String,
4238    /// URL to the MCP server.
4239    pub url: String,
4240    /// HTTP headers to set when making requests to the MCP server.
4241    #[serde_as(deserialize_as = "DefaultOnNull")]
4242    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
4243    pub headers: Vec<HttpHeader>,
4244    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4245    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4246    /// these keys.
4247    ///
4248    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4249    #[serde_as(deserialize_as = "DefaultOnError")]
4250    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
4251    #[serde(default)]
4252    #[serde(rename = "_meta")]
4253    pub meta: Option<Meta>,
4254}
4255
4256impl McpServerHttp {
4257    /// Builds [`McpServerHttp`] with the required fields set. Optional fields start unset or empty.
4258    #[must_use]
4259    pub fn new(name: impl Into<String>, url: impl Into<String>) -> Self {
4260        Self {
4261            name: name.into(),
4262            url: url.into(),
4263            headers: Vec::new(),
4264            meta: None,
4265        }
4266    }
4267
4268    /// HTTP headers to set when making requests to the MCP server.
4269    #[must_use]
4270    pub fn headers(mut self, headers: Vec<HttpHeader>) -> Self {
4271        self.headers = headers;
4272        self
4273    }
4274
4275    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4276    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4277    /// these keys.
4278    ///
4279    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4280    #[must_use]
4281    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
4282        self.meta = meta.into_option();
4283        self
4284    }
4285}
4286
4287/// SSE transport configuration for MCP.
4288#[serde_as]
4289#[skip_serializing_none]
4290#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
4291#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
4292#[serde(rename_all = "camelCase")]
4293#[non_exhaustive]
4294pub struct McpServerSse {
4295    /// Human-readable name identifying this MCP server.
4296    pub name: String,
4297    /// URL to the MCP server.
4298    pub url: String,
4299    /// HTTP headers to set when making requests to the MCP server.
4300    #[serde_as(deserialize_as = "DefaultOnNull")]
4301    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
4302    pub headers: Vec<HttpHeader>,
4303    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4304    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4305    /// these keys.
4306    ///
4307    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4308    #[serde_as(deserialize_as = "DefaultOnError")]
4309    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
4310    #[serde(default)]
4311    #[serde(rename = "_meta")]
4312    pub meta: Option<Meta>,
4313}
4314
4315impl McpServerSse {
4316    /// Builds [`McpServerSse`] with the required fields set. Optional fields start unset or empty.
4317    #[must_use]
4318    pub fn new(name: impl Into<String>, url: impl Into<String>) -> Self {
4319        Self {
4320            name: name.into(),
4321            url: url.into(),
4322            headers: Vec::new(),
4323            meta: None,
4324        }
4325    }
4326
4327    /// HTTP headers to set when making requests to the MCP server.
4328    #[must_use]
4329    pub fn headers(mut self, headers: Vec<HttpHeader>) -> Self {
4330        self.headers = headers;
4331        self
4332    }
4333
4334    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4335    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4336    /// these keys.
4337    ///
4338    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4339    #[must_use]
4340    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
4341        self.meta = meta.into_option();
4342        self
4343    }
4344}
4345
4346/// **UNSTABLE**
4347///
4348/// This capability is not part of the spec yet, and may be removed or changed at any point.
4349///
4350/// Unique identifier for an MCP server using the ACP transport.
4351///
4352/// The value is opaque and generated by the ACP component providing the MCP server. It is
4353/// used by `mcp/message` to route requests to the component that declared the server.
4354#[cfg(feature = "unstable_mcp_over_acp")]
4355#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
4356#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, Display, From)]
4357#[serde(transparent)]
4358#[from(Arc<str>, String, &'static str)]
4359#[non_exhaustive]
4360pub struct McpServerAcpId(pub Arc<str>);
4361
4362#[cfg(feature = "unstable_mcp_over_acp")]
4363impl McpServerAcpId {
4364    /// Wraps a protocol string as a typed [`McpServerAcpId`].
4365    #[must_use]
4366    pub fn new(id: impl Into<Arc<str>>) -> Self {
4367        Self(id.into())
4368    }
4369}
4370
4371/// **UNSTABLE**
4372///
4373/// This capability is not part of the spec yet, and may be removed or changed at any point.
4374///
4375/// ACP transport configuration for MCP.
4376///
4377/// The MCP server is provided by an ACP component and communicates over the ACP channel
4378/// using `mcp/message`.
4379#[serde_as]
4380#[skip_serializing_none]
4381#[cfg(feature = "unstable_mcp_over_acp")]
4382#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
4383#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
4384#[serde(rename_all = "camelCase")]
4385#[non_exhaustive]
4386pub struct McpServerAcp {
4387    /// Human-readable name identifying this MCP server.
4388    pub name: String,
4389    /// Unique identifier for this MCP server, generated by the component providing it.
4390    ///
4391    /// Providers MUST NOT reuse an ID for multiple ACP-transport MCP servers that are visible
4392    /// on the same ACP connection.
4393    pub server_id: McpServerAcpId,
4394    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4395    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4396    /// these keys.
4397    ///
4398    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4399    #[serde_as(deserialize_as = "DefaultOnError")]
4400    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
4401    #[serde(default)]
4402    #[serde(rename = "_meta")]
4403    pub meta: Option<Meta>,
4404}
4405
4406#[cfg(feature = "unstable_mcp_over_acp")]
4407impl McpServerAcp {
4408    /// Builds [`McpServerAcp`] with the required fields set. Optional fields start unset or empty.
4409    #[must_use]
4410    pub fn new(name: impl Into<String>, id: impl Into<McpServerAcpId>) -> Self {
4411        Self {
4412            name: name.into(),
4413            server_id: id.into(),
4414            meta: None,
4415        }
4416    }
4417
4418    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4419    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4420    /// these keys.
4421    ///
4422    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4423    #[must_use]
4424    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
4425        self.meta = meta.into_option();
4426        self
4427    }
4428}
4429
4430/// Stdio transport configuration for MCP.
4431#[serde_as]
4432#[skip_serializing_none]
4433#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
4434#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
4435#[serde(rename_all = "camelCase")]
4436#[non_exhaustive]
4437pub struct McpServerStdio {
4438    /// Human-readable name identifying this MCP server.
4439    pub name: String,
4440    /// Absolute path to the MCP server executable.
4441    pub command: PathBuf,
4442    /// Command-line arguments to pass to the MCP server.
4443    #[serde_as(deserialize_as = "DefaultOnNull")]
4444    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
4445    pub args: Vec<String>,
4446    /// Environment variables to set when launching the MCP server.
4447    #[serde_as(deserialize_as = "DefaultOnNull")]
4448    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-null" = true)))]
4449    pub env: Vec<EnvVariable>,
4450    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4451    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4452    /// these keys.
4453    ///
4454    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4455    #[serde_as(deserialize_as = "DefaultOnError")]
4456    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
4457    #[serde(default)]
4458    #[serde(rename = "_meta")]
4459    pub meta: Option<Meta>,
4460}
4461
4462impl McpServerStdio {
4463    /// Builds [`McpServerStdio`] with the required fields set. Optional fields start unset or empty.
4464    #[must_use]
4465    pub fn new(name: impl Into<String>, command: impl Into<PathBuf>) -> Self {
4466        Self {
4467            name: name.into(),
4468            command: command.into(),
4469            args: Vec::new(),
4470            env: Vec::new(),
4471            meta: None,
4472        }
4473    }
4474
4475    /// Command-line arguments to pass to the MCP server.
4476    #[must_use]
4477    pub fn args(mut self, args: Vec<String>) -> Self {
4478        self.args = args;
4479        self
4480    }
4481
4482    /// Environment variables to set when launching the MCP server.
4483    #[must_use]
4484    pub fn env(mut self, env: Vec<EnvVariable>) -> Self {
4485        self.env = env;
4486        self
4487    }
4488
4489    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4490    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4491    /// these keys.
4492    ///
4493    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4494    #[must_use]
4495    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
4496        self.meta = meta.into_option();
4497        self
4498    }
4499}
4500
4501/// An environment variable to set when launching an MCP server.
4502#[serde_as]
4503#[skip_serializing_none]
4504#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
4505#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
4506#[serde(rename_all = "camelCase")]
4507#[non_exhaustive]
4508pub struct EnvVariable {
4509    /// The name of the environment variable.
4510    pub name: String,
4511    /// The value to set for the environment variable.
4512    pub value: String,
4513    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4514    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4515    /// these keys.
4516    ///
4517    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4518    #[serde_as(deserialize_as = "DefaultOnError")]
4519    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
4520    #[serde(default)]
4521    #[serde(rename = "_meta")]
4522    pub meta: Option<Meta>,
4523}
4524
4525impl EnvVariable {
4526    /// Builds [`EnvVariable`] with the required fields set. Optional fields start unset or empty.
4527    #[must_use]
4528    pub fn new(name: impl Into<String>, value: impl Into<String>) -> Self {
4529        Self {
4530            name: name.into(),
4531            value: value.into(),
4532            meta: None,
4533        }
4534    }
4535
4536    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4537    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4538    /// these keys.
4539    ///
4540    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4541    #[must_use]
4542    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
4543        self.meta = meta.into_option();
4544        self
4545    }
4546}
4547
4548/// An HTTP header to set when making requests to the MCP server.
4549#[serde_as]
4550#[skip_serializing_none]
4551#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
4552#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
4553#[serde(rename_all = "camelCase")]
4554#[non_exhaustive]
4555pub struct HttpHeader {
4556    /// The name of the HTTP header.
4557    pub name: String,
4558    /// The value to set for the HTTP header.
4559    pub value: String,
4560    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4561    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4562    /// these keys.
4563    ///
4564    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4565    #[serde_as(deserialize_as = "DefaultOnError")]
4566    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
4567    #[serde(default)]
4568    #[serde(rename = "_meta")]
4569    pub meta: Option<Meta>,
4570}
4571
4572impl HttpHeader {
4573    /// Builds [`HttpHeader`] with the required fields set. Optional fields start unset or empty.
4574    #[must_use]
4575    pub fn new(name: impl Into<String>, value: impl Into<String>) -> Self {
4576        Self {
4577            name: name.into(),
4578            value: value.into(),
4579            meta: None,
4580        }
4581    }
4582
4583    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4584    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4585    /// these keys.
4586    ///
4587    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4588    #[must_use]
4589    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
4590        self.meta = meta.into_option();
4591        self
4592    }
4593}
4594
4595// System prompt
4596
4597/// Client-provided system-level instructions for a session.
4598///
4599/// Clients MUST only send this when the Agent advertises
4600/// `sessionCapabilities.systemPrompt`. Agents that cannot apply it, for example
4601/// because of an unadvertised mode or an unsupported content block type, MUST
4602/// return an error instead of creating, loading, or resuming the session.
4603#[serde_as]
4604#[skip_serializing_none]
4605#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
4606#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
4607#[serde(rename_all = "camelCase")]
4608#[non_exhaustive]
4609pub struct SystemPrompt {
4610    /// How the Agent combines `content` with its own instructions.
4611    ///
4612    /// Required. Agents MUST return an error for a mode they do not support rather than
4613    /// treating it as `append` or `override`.
4614    pub mode: SystemPromptMode,
4615    /// The system prompt content.
4616    ///
4617    /// Agents advertising the capability MUST accept `text` content blocks.
4618    /// Clients MUST NOT send other content block types until a future
4619    /// capability allows them, and Agents MUST return an error for content
4620    /// blocks they do not support.
4621    ///
4622    /// Clients MUST NOT send an empty array. Agents MAY reject one with
4623    /// `-32602` without creating, loading, or resuming the session.
4624    pub content: Vec<ContentBlock>,
4625    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4626    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4627    /// these keys.
4628    ///
4629    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4630    #[serde_as(deserialize_as = "DefaultOnError")]
4631    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
4632    #[serde(default)]
4633    #[serde(rename = "_meta")]
4634    pub meta: Option<Meta>,
4635}
4636
4637impl SystemPrompt {
4638    /// Builds [`SystemPrompt`] with the required fields set. Optional fields start unset or empty.
4639    ///
4640    /// `mode` starts as [`SystemPromptMode::Append`]. Use [`SystemPrompt::mode`]
4641    /// to request another mode.
4642    #[must_use]
4643    pub fn new(content: Vec<ContentBlock>) -> Self {
4644        Self {
4645            mode: SystemPromptMode::default(),
4646            content,
4647            meta: None,
4648        }
4649    }
4650
4651    /// How the Agent combines `content` with its own instructions.
4652    #[must_use]
4653    pub fn mode(mut self, mode: SystemPromptMode) -> Self {
4654        self.mode = mode;
4655        self
4656    }
4657
4658    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4659    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4660    /// these keys.
4661    ///
4662    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4663    #[must_use]
4664    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
4665        self.meta = meta.into_option();
4666        self
4667    }
4668}
4669
4670/// How the Agent combines a client-provided system prompt with its own instructions.
4671///
4672/// Unknown modes are preserved so they can be stored,
4673/// proxied, or forwarded. An Agent MUST return an error for a mode it does not
4674/// support rather than treating it as `append` or `override`.
4675#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
4676#[derive(Debug, Default, Clone, PartialEq, Eq, Serialize, Deserialize)]
4677#[serde(rename_all = "snake_case")]
4678#[non_exhaustive]
4679pub enum SystemPromptMode {
4680    /// Add the content to the Agent's own instructions rather than replacing them.
4681    ///
4682    /// Every Agent that advertises `sessionCapabilities.systemPrompt` supports this mode.
4683    /// Agents SHOULD give the content system-level precedence, for example in the
4684    /// model's system prompt or developer instructions rather than in user-turn
4685    /// content. Where it is placed and how it is formatted is implementation-defined.
4686    #[default]
4687    Append,
4688    /// Replace the Agent's built-in default instructions with the content.
4689    ///
4690    /// This does not change tool availability, MCP servers, permissions, or session
4691    /// configuration. Context the Agent supplies from the workspace or environment
4692    /// MAY still be included. Clients that use this mode take responsibility for any
4693    /// tool guidance or safety instructions the Agent's default instructions
4694    /// provided, and MUST only use it when the Agent advertises
4695    /// `sessionCapabilities.systemPrompt.mode.override`.
4696    Override,
4697    /// Custom or future system prompt mode.
4698    ///
4699    /// Values beginning with `_` are reserved for implementation-specific
4700    /// extensions. Unknown values that do not begin with `_` are reserved for
4701    /// future ACP variants.
4702    #[serde(untagged)]
4703    Other(String),
4704}
4705
4706// Prompt
4707
4708/// Request parameters for sending a user prompt to the agent.
4709///
4710/// Contains the user's message and any additional context.
4711///
4712/// See protocol docs: [User Message](https://agentclientprotocol.com/protocol/v1/prompt-turn#1-user-message)
4713#[serde_as]
4714#[skip_serializing_none]
4715#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
4716#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
4717#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_PROMPT_METHOD_NAME)))]
4718#[serde(rename_all = "camelCase")]
4719#[non_exhaustive]
4720pub struct PromptRequest {
4721    /// The ID of the session to send this user message to
4722    pub session_id: SessionId,
4723    /// The blocks of content that compose the user's message.
4724    ///
4725    /// As a baseline, the Agent MUST support `text` and `resource_link` content blocks,
4726    /// while other variants are optionally enabled via `PromptCapabilities`.
4727    ///
4728    /// The Client MUST adapt its interface according to `PromptCapabilities`.
4729    ///
4730    /// The client MAY include referenced pieces of context as either
4731    /// `resource` or `resource_link` content blocks.
4732    ///
4733    /// When available, `resource` is preferred
4734    /// as it avoids extra round-trips and allows the message to include
4735    /// pieces of context from sources the agent may not have access to.
4736    pub prompt: Vec<ContentBlock>,
4737    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4738    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4739    /// these keys.
4740    ///
4741    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4742    #[serde_as(deserialize_as = "DefaultOnError")]
4743    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
4744    #[serde(default)]
4745    #[serde(rename = "_meta")]
4746    pub meta: Option<Meta>,
4747}
4748
4749impl PromptRequest {
4750    /// Builds [`PromptRequest`] with the required request fields set. Optional fields start unset or empty.
4751    #[must_use]
4752    pub fn new(session_id: impl Into<SessionId>, prompt: Vec<ContentBlock>) -> Self {
4753        Self {
4754            session_id: session_id.into(),
4755            prompt,
4756            meta: None,
4757        }
4758    }
4759
4760    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4761    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4762    /// these keys.
4763    ///
4764    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4765    #[must_use]
4766    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
4767        self.meta = meta.into_option();
4768        self
4769    }
4770}
4771
4772/// Response from processing a user prompt.
4773///
4774/// See protocol docs: [Check for Completion](https://agentclientprotocol.com/protocol/v1/prompt-turn#4-check-for-completion)
4775#[serde_as]
4776#[skip_serializing_none]
4777#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
4778#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
4779#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_PROMPT_METHOD_NAME)))]
4780#[serde(rename_all = "camelCase")]
4781#[non_exhaustive]
4782pub struct PromptResponse {
4783    /// Indicates why the agent stopped processing the turn.
4784    pub stop_reason: StopReason,
4785    /// **UNSTABLE**
4786    ///
4787    /// This capability is not part of the spec yet, and may be removed or changed at any point.
4788    ///
4789    /// Token usage for this turn (optional).
4790    #[cfg(feature = "unstable_end_turn_token_usage")]
4791    #[serde_as(deserialize_as = "DefaultOnError")]
4792    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
4793    #[serde(default)]
4794    pub usage: Option<Usage>,
4795    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4796    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4797    /// these keys.
4798    ///
4799    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4800    #[serde_as(deserialize_as = "DefaultOnError")]
4801    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
4802    #[serde(default)]
4803    #[serde(rename = "_meta")]
4804    pub meta: Option<Meta>,
4805}
4806
4807impl PromptResponse {
4808    /// Builds [`PromptResponse`] with the required response fields set. Optional fields start unset or empty.
4809    #[must_use]
4810    pub fn new(stop_reason: StopReason) -> Self {
4811        Self {
4812            stop_reason,
4813            #[cfg(feature = "unstable_end_turn_token_usage")]
4814            usage: None,
4815            meta: None,
4816        }
4817    }
4818
4819    /// **UNSTABLE**
4820    ///
4821    /// This capability is not part of the spec yet, and may be removed or changed at any point.
4822    ///
4823    /// Token usage for this turn.
4824    #[cfg(feature = "unstable_end_turn_token_usage")]
4825    #[must_use]
4826    pub fn usage(mut self, usage: impl IntoOption<Usage>) -> Self {
4827        self.usage = usage.into_option();
4828        self
4829    }
4830
4831    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4832    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4833    /// these keys.
4834    ///
4835    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4836    #[must_use]
4837    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
4838        self.meta = meta.into_option();
4839        self
4840    }
4841}
4842
4843/// Reasons why an agent stops processing a prompt turn.
4844///
4845/// See protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/v1/prompt-turn#stop-reasons)
4846#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
4847#[derive(Debug, Copy, Clone, Eq, PartialEq, Serialize, Deserialize)]
4848#[serde(rename_all = "snake_case")]
4849#[non_exhaustive]
4850pub enum StopReason {
4851    /// The turn ended successfully.
4852    EndTurn,
4853    /// The turn ended because the agent reached the maximum number of tokens.
4854    MaxTokens,
4855    /// The turn ended because the agent reached the maximum number of allowed
4856    /// agent requests between user turns.
4857    MaxTurnRequests,
4858    /// The turn ended because the agent refused to continue. The user prompt
4859    /// and everything that comes after it won't be included in the next
4860    /// prompt, so this should be reflected in the UI.
4861    Refusal,
4862    /// The turn was cancelled by the client via `session/cancel`.
4863    ///
4864    /// This stop reason MUST be returned when the client sends a `session/cancel`
4865    /// notification, even if the cancellation causes exceptions in underlying operations.
4866    /// Agents SHOULD catch these exceptions and return this semantically meaningful
4867    /// response to confirm successful cancellation.
4868    Cancelled,
4869}
4870
4871/// **UNSTABLE**
4872///
4873/// This capability is not part of the spec yet, and may be removed or changed at any point.
4874///
4875/// Token usage information for a prompt turn.
4876#[cfg(feature = "unstable_end_turn_token_usage")]
4877#[serde_as]
4878#[skip_serializing_none]
4879#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
4880#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
4881#[serde(rename_all = "camelCase")]
4882#[non_exhaustive]
4883pub struct Usage {
4884    /// Sum of all token types across session.
4885    pub total_tokens: u64,
4886    /// Total input tokens across all turns.
4887    pub input_tokens: u64,
4888    /// Total output tokens across all turns.
4889    pub output_tokens: u64,
4890    /// Total thought/reasoning tokens
4891    #[serde_as(deserialize_as = "DefaultOnError")]
4892    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
4893    #[serde(default)]
4894    pub thought_tokens: Option<u64>,
4895    /// Total cache read tokens.
4896    #[serde_as(deserialize_as = "DefaultOnError")]
4897    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
4898    #[serde(default)]
4899    pub cached_read_tokens: Option<u64>,
4900    /// Total cache write tokens.
4901    #[serde_as(deserialize_as = "DefaultOnError")]
4902    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
4903    #[serde(default)]
4904    pub cached_write_tokens: Option<u64>,
4905    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4906    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4907    /// these keys.
4908    ///
4909    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4910    #[serde_as(deserialize_as = "DefaultOnError")]
4911    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
4912    #[serde(default)]
4913    #[serde(rename = "_meta")]
4914    pub meta: Option<Meta>,
4915}
4916
4917#[cfg(feature = "unstable_end_turn_token_usage")]
4918impl Usage {
4919    /// Builds [`Usage`] with the required fields set. Optional fields start unset or empty.
4920    #[must_use]
4921    pub fn new(total_tokens: u64, input_tokens: u64, output_tokens: u64) -> Self {
4922        Self {
4923            total_tokens,
4924            input_tokens,
4925            output_tokens,
4926            thought_tokens: None,
4927            cached_read_tokens: None,
4928            cached_write_tokens: None,
4929            meta: None,
4930        }
4931    }
4932
4933    /// Total thought/reasoning tokens
4934    #[must_use]
4935    pub fn thought_tokens(mut self, thought_tokens: impl IntoOption<u64>) -> Self {
4936        self.thought_tokens = thought_tokens.into_option();
4937        self
4938    }
4939
4940    /// Total cache read tokens.
4941    #[must_use]
4942    pub fn cached_read_tokens(mut self, cached_read_tokens: impl IntoOption<u64>) -> Self {
4943        self.cached_read_tokens = cached_read_tokens.into_option();
4944        self
4945    }
4946
4947    /// Total cache write tokens.
4948    #[must_use]
4949    pub fn cached_write_tokens(mut self, cached_write_tokens: impl IntoOption<u64>) -> Self {
4950        self.cached_write_tokens = cached_write_tokens.into_option();
4951        self
4952    }
4953
4954    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
4955    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
4956    /// these keys.
4957    ///
4958    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
4959    #[must_use]
4960    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
4961        self.meta = meta.into_option();
4962        self
4963    }
4964}
4965
4966// Providers
4967
4968/// **UNSTABLE**
4969///
4970/// This capability is not part of the spec yet, and may be removed or changed at any point.
4971///
4972/// Well-known API protocol identifiers for LLM providers.
4973///
4974/// Agents and clients MUST handle unknown protocol identifiers gracefully.
4975///
4976/// Protocol names beginning with `_` are free for custom use, like other ACP extension methods.
4977/// Protocol names that do not begin with `_` are reserved for the ACP spec.
4978#[cfg(feature = "unstable_llm_providers")]
4979#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
4980#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
4981#[serde(rename_all = "snake_case")]
4982#[non_exhaustive]
4983pub enum LlmProtocol {
4984    /// Anthropic API protocol.
4985    Anthropic,
4986    /// OpenAI API protocol.
4987    #[serde(rename = "openai")]
4988    OpenAi,
4989    /// Azure OpenAI API protocol.
4990    Azure,
4991    /// Google Vertex AI API protocol.
4992    Vertex,
4993    /// AWS Bedrock API protocol.
4994    Bedrock,
4995    /// Unknown or custom protocol.
4996    #[serde(untagged)]
4997    Other(String),
4998}
4999
5000/// **UNSTABLE**
5001///
5002/// This capability is not part of the spec yet, and may be removed or changed at any point.
5003///
5004/// Current effective non-secret routing configuration for a provider.
5005#[cfg(feature = "unstable_llm_providers")]
5006#[serde_as]
5007#[skip_serializing_none]
5008#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5009#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
5010#[serde(rename_all = "camelCase")]
5011#[non_exhaustive]
5012pub struct ProviderCurrentConfig {
5013    /// Protocol currently used by this provider.
5014    pub api_type: LlmProtocol,
5015    /// Base URL currently used by this provider.
5016    pub base_url: String,
5017    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5018    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5019    /// these keys.
5020    ///
5021    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5022    #[serde_as(deserialize_as = "DefaultOnError")]
5023    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5024    #[serde(default)]
5025    #[serde(rename = "_meta")]
5026    pub meta: Option<Meta>,
5027}
5028
5029#[cfg(feature = "unstable_llm_providers")]
5030impl ProviderCurrentConfig {
5031    /// Builds [`ProviderCurrentConfig`] with the required fields set. Optional fields start unset or empty.
5032    #[must_use]
5033    pub fn new(api_type: LlmProtocol, base_url: impl Into<String>) -> Self {
5034        Self {
5035            api_type,
5036            base_url: base_url.into(),
5037            meta: None,
5038        }
5039    }
5040
5041    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5042    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5043    /// these keys.
5044    ///
5045    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5046    #[must_use]
5047    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5048        self.meta = meta.into_option();
5049        self
5050    }
5051}
5052
5053/// **UNSTABLE**
5054///
5055/// This capability is not part of the spec yet, and may be removed or changed at any point.
5056///
5057/// Unique identifier for a configurable LLM provider.
5058#[cfg(feature = "unstable_llm_providers")]
5059#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5060#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, Display, From)]
5061#[serde(transparent)]
5062#[from(Arc<str>, String, &'static str)]
5063#[non_exhaustive]
5064pub struct ProviderId(pub Arc<str>);
5065
5066#[cfg(feature = "unstable_llm_providers")]
5067impl ProviderId {
5068    /// Wraps a protocol string as a typed [`ProviderId`].
5069    #[must_use]
5070    pub fn new(id: impl Into<Arc<str>>) -> Self {
5071        Self(id.into())
5072    }
5073}
5074
5075/// **UNSTABLE**
5076///
5077/// This capability is not part of the spec yet, and may be removed or changed at any point.
5078///
5079/// Information about a configurable LLM provider.
5080#[cfg(feature = "unstable_llm_providers")]
5081#[serde_as]
5082#[skip_serializing_none]
5083#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5084#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
5085#[serde(rename_all = "camelCase")]
5086#[non_exhaustive]
5087pub struct ProviderInfo {
5088    /// Provider identifier, for example "main" or "openai".
5089    pub provider_id: ProviderId,
5090    /// Supported protocol types for this provider.
5091    #[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_>>")]
5092    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
5093    pub supported: Vec<LlmProtocol>,
5094    /// Whether this provider is mandatory and cannot be disabled via `providers/disable`.
5095    /// If true, clients MUST NOT call `providers/disable` for this provider ID.
5096    pub required: bool,
5097    /// Current effective non-secret routing config.
5098    /// Null or omitted means provider is disabled.
5099    #[serde(default)]
5100    pub current: Option<ProviderCurrentConfig>,
5101    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5102    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5103    /// these keys.
5104    ///
5105    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5106    #[serde_as(deserialize_as = "DefaultOnError")]
5107    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5108    #[serde(default)]
5109    #[serde(rename = "_meta")]
5110    pub meta: Option<Meta>,
5111}
5112
5113#[cfg(feature = "unstable_llm_providers")]
5114impl ProviderInfo {
5115    /// Builds [`ProviderInfo`] with the required fields set. Optional fields start unset or empty.
5116    #[must_use]
5117    pub fn new(
5118        provider_id: impl Into<ProviderId>,
5119        supported: Vec<LlmProtocol>,
5120        required: bool,
5121        current: impl IntoOption<ProviderCurrentConfig>,
5122    ) -> Self {
5123        Self {
5124            provider_id: provider_id.into(),
5125            supported,
5126            required,
5127            current: current.into_option(),
5128            meta: None,
5129        }
5130    }
5131
5132    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5133    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5134    /// these keys.
5135    ///
5136    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5137    #[must_use]
5138    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5139        self.meta = meta.into_option();
5140        self
5141    }
5142}
5143
5144#[cfg(feature = "unstable_llm_providers")]
5145crate::serde_util::default_on_null! {
5146    /// **UNSTABLE**
5147    ///
5148    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5149    ///
5150    /// Request parameters for `providers/list`.
5151    #[serde_as]
5152    #[skip_serializing_none]
5153    #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5154    #[derive(Default, Debug, Clone, Serialize, PartialEq, Eq)]
5155    #[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = PROVIDERS_LIST_METHOD_NAME)))]
5156    #[serde(rename_all = "camelCase")]
5157    #[non_exhaustive]
5158    pub struct ListProvidersRequest {
5159        /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5160        /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5161        /// these keys.
5162        ///
5163        /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5164        #[serde_as(deserialize_as = "DefaultOnError")]
5165        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5166        #[serde(default)]
5167        #[serde(rename = "_meta")]
5168        pub meta: Option<Meta>,
5169    }
5170}
5171
5172#[cfg(feature = "unstable_llm_providers")]
5173impl ListProvidersRequest {
5174    /// Builds [`ListProvidersRequest`] with the required request fields set. Optional fields start unset or empty.
5175    #[must_use]
5176    pub fn new() -> Self {
5177        Self::default()
5178    }
5179
5180    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5181    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5182    /// these keys.
5183    ///
5184    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5185    #[must_use]
5186    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5187        self.meta = meta.into_option();
5188        self
5189    }
5190}
5191
5192/// **UNSTABLE**
5193///
5194/// This capability is not part of the spec yet, and may be removed or changed at any point.
5195///
5196/// Response to `providers/list`.
5197#[cfg(feature = "unstable_llm_providers")]
5198#[serde_as]
5199#[skip_serializing_none]
5200#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5201#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
5202#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = PROVIDERS_LIST_METHOD_NAME)))]
5203#[serde(rename_all = "camelCase")]
5204#[non_exhaustive]
5205pub struct ListProvidersResponse {
5206    /// Configurable providers with current routing info suitable for UI display.
5207    pub providers: Vec<ProviderInfo>,
5208    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5209    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5210    /// these keys.
5211    ///
5212    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5213    #[serde_as(deserialize_as = "DefaultOnError")]
5214    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5215    #[serde(default)]
5216    #[serde(rename = "_meta")]
5217    pub meta: Option<Meta>,
5218}
5219
5220#[cfg(feature = "unstable_llm_providers")]
5221impl ListProvidersResponse {
5222    /// Builds [`ListProvidersResponse`] with the required response fields set. Optional fields start unset or empty.
5223    #[must_use]
5224    pub fn new(providers: Vec<ProviderInfo>) -> Self {
5225        Self {
5226            providers,
5227            meta: None,
5228        }
5229    }
5230
5231    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5232    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5233    /// these keys.
5234    ///
5235    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5236    #[must_use]
5237    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5238        self.meta = meta.into_option();
5239        self
5240    }
5241}
5242
5243/// **UNSTABLE**
5244///
5245/// This capability is not part of the spec yet, and may be removed or changed at any point.
5246///
5247/// Request parameters for `providers/set`.
5248///
5249/// Replaces the full configuration for one provider ID.
5250#[cfg(feature = "unstable_llm_providers")]
5251#[serde_as]
5252#[skip_serializing_none]
5253#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5254#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
5255#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = PROVIDERS_SET_METHOD_NAME)))]
5256#[serde(rename_all = "camelCase")]
5257#[non_exhaustive]
5258pub struct SetProviderRequest {
5259    /// Provider ID to configure.
5260    pub provider_id: ProviderId,
5261    /// Protocol type for this provider.
5262    pub api_type: LlmProtocol,
5263    /// Base URL for requests sent through this provider.
5264    pub base_url: String,
5265    /// Full headers map for this provider.
5266    /// May include authorization, routing, or other integration-specific headers.
5267    #[serde(default, skip_serializing_if = "IndexMap::is_empty")]
5268    pub headers: IndexMap<String, String>,
5269    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5270    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5271    /// these keys.
5272    ///
5273    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5274    #[serde_as(deserialize_as = "DefaultOnError")]
5275    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5276    #[serde(default)]
5277    #[serde(rename = "_meta")]
5278    pub meta: Option<Meta>,
5279}
5280
5281#[cfg(feature = "unstable_llm_providers")]
5282impl SetProviderRequest {
5283    /// Builds [`SetProviderRequest`] with the required request fields set. Optional fields start unset or empty.
5284    #[must_use]
5285    pub fn new(
5286        provider_id: impl Into<ProviderId>,
5287        api_type: LlmProtocol,
5288        base_url: impl Into<String>,
5289    ) -> Self {
5290        Self {
5291            provider_id: provider_id.into(),
5292            api_type,
5293            base_url: base_url.into(),
5294            headers: IndexMap::new(),
5295            meta: None,
5296        }
5297    }
5298
5299    /// Full headers map for this provider.
5300    /// May include authorization, routing, or other integration-specific headers.
5301    #[must_use]
5302    pub fn headers(mut self, headers: IndexMap<String, String>) -> Self {
5303        self.headers = headers;
5304        self
5305    }
5306
5307    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5308    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5309    /// these keys.
5310    ///
5311    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5312    #[must_use]
5313    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5314        self.meta = meta.into_option();
5315        self
5316    }
5317}
5318
5319#[cfg(feature = "unstable_llm_providers")]
5320crate::serde_util::default_on_null! {
5321    /// **UNSTABLE**
5322    ///
5323    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5324    ///
5325    /// Response to `providers/set`.
5326    #[serde_as]
5327    #[skip_serializing_none]
5328    #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5329    #[derive(Default, Debug, Clone, Serialize, PartialEq, Eq)]
5330    #[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = PROVIDERS_SET_METHOD_NAME)))]
5331    #[serde(rename_all = "camelCase")]
5332    #[non_exhaustive]
5333    pub struct SetProviderResponse {
5334        /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5335        /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5336        /// these keys.
5337        ///
5338        /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5339        #[serde_as(deserialize_as = "DefaultOnError")]
5340        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5341        #[serde(default)]
5342        #[serde(rename = "_meta")]
5343        pub meta: Option<Meta>,
5344    }
5345}
5346
5347#[cfg(feature = "unstable_llm_providers")]
5348impl SetProviderResponse {
5349    /// Builds [`SetProviderResponse`] with the required response fields set. Optional fields start unset or empty.
5350    #[must_use]
5351    pub fn new() -> Self {
5352        Self::default()
5353    }
5354
5355    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5356    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5357    /// these keys.
5358    ///
5359    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5360    #[must_use]
5361    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5362        self.meta = meta.into_option();
5363        self
5364    }
5365}
5366
5367/// **UNSTABLE**
5368///
5369/// This capability is not part of the spec yet, and may be removed or changed at any point.
5370///
5371/// Request parameters for `providers/disable`.
5372#[cfg(feature = "unstable_llm_providers")]
5373#[serde_as]
5374#[skip_serializing_none]
5375#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5376#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
5377#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = PROVIDERS_DISABLE_METHOD_NAME)))]
5378#[serde(rename_all = "camelCase")]
5379#[non_exhaustive]
5380pub struct DisableProviderRequest {
5381    /// Provider ID to disable.
5382    pub provider_id: ProviderId,
5383    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5384    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5385    /// these keys.
5386    ///
5387    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5388    #[serde_as(deserialize_as = "DefaultOnError")]
5389    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5390    #[serde(default)]
5391    #[serde(rename = "_meta")]
5392    pub meta: Option<Meta>,
5393}
5394
5395#[cfg(feature = "unstable_llm_providers")]
5396impl DisableProviderRequest {
5397    /// Builds [`DisableProviderRequest`] with the required request fields set. Optional fields start unset or empty.
5398    #[must_use]
5399    pub fn new(provider_id: impl Into<ProviderId>) -> Self {
5400        Self {
5401            provider_id: provider_id.into(),
5402            meta: None,
5403        }
5404    }
5405
5406    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5407    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5408    /// these keys.
5409    ///
5410    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5411    #[must_use]
5412    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5413        self.meta = meta.into_option();
5414        self
5415    }
5416}
5417
5418#[cfg(feature = "unstable_llm_providers")]
5419crate::serde_util::default_on_null! {
5420    /// **UNSTABLE**
5421    ///
5422    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5423    ///
5424    /// Response to `providers/disable`.
5425    #[serde_as]
5426    #[skip_serializing_none]
5427    #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5428    #[derive(Default, Debug, Clone, Serialize, PartialEq, Eq)]
5429    #[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = PROVIDERS_DISABLE_METHOD_NAME)))]
5430    #[serde(rename_all = "camelCase")]
5431    #[non_exhaustive]
5432    pub struct DisableProviderResponse {
5433        /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5434        /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5435        /// these keys.
5436        ///
5437        /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5438        #[serde_as(deserialize_as = "DefaultOnError")]
5439        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5440        #[serde(default)]
5441        #[serde(rename = "_meta")]
5442        pub meta: Option<Meta>,
5443    }
5444}
5445
5446#[cfg(feature = "unstable_llm_providers")]
5447impl DisableProviderResponse {
5448    /// Builds [`DisableProviderResponse`] with the required response fields set. Optional fields start unset or empty.
5449    #[must_use]
5450    pub fn new() -> Self {
5451        Self::default()
5452    }
5453
5454    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5455    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5456    /// these keys.
5457    ///
5458    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5459    #[must_use]
5460    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5461        self.meta = meta.into_option();
5462        self
5463    }
5464}
5465
5466// Capabilities
5467
5468/// Capabilities supported by the agent.
5469///
5470/// Advertised during initialization to inform the client about
5471/// available features and content types.
5472///
5473/// See protocol docs: [Agent Capabilities](https://agentclientprotocol.com/protocol/v1/initialization#agent-capabilities)
5474#[serde_as]
5475#[skip_serializing_none]
5476#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5477#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
5478#[serde(rename_all = "camelCase")]
5479#[non_exhaustive]
5480pub struct AgentCapabilities {
5481    /// Whether the agent supports `session/load`.
5482    #[serde_as(deserialize_as = "DefaultOnError")]
5483    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5484    #[serde(default)]
5485    pub load_session: bool,
5486    /// Prompt capabilities supported by the agent.
5487    #[serde_as(deserialize_as = "DefaultOnError")]
5488    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5489    #[serde(default)]
5490    pub prompt_capabilities: PromptCapabilities,
5491    /// MCP capabilities supported by the agent.
5492    #[serde_as(deserialize_as = "DefaultOnError")]
5493    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5494    #[serde(default)]
5495    pub mcp_capabilities: McpCapabilities,
5496    /// Session lifecycle and prompt capabilities advertised by the agent.
5497    #[serde_as(deserialize_as = "DefaultOnError")]
5498    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5499    #[serde(default)]
5500    pub session_capabilities: SessionCapabilities,
5501    /// Authentication-related capabilities supported by the agent.
5502    #[serde_as(deserialize_as = "DefaultOnError")]
5503    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5504    #[serde(default)]
5505    pub auth: AgentAuthCapabilities,
5506    /// **UNSTABLE**
5507    ///
5508    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5509    ///
5510    /// Provider configuration capabilities supported by the agent.
5511    ///
5512    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5513    /// Supplying `{}` means the agent supports provider configuration methods.
5514    #[cfg(feature = "unstable_llm_providers")]
5515    #[serde_as(deserialize_as = "DefaultOnError")]
5516    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5517    #[serde(default)]
5518    pub providers: Option<ProvidersCapabilities>,
5519    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5520    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5521    /// these keys.
5522    ///
5523    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5524    #[serde_as(deserialize_as = "DefaultOnError")]
5525    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5526    #[serde(default)]
5527    #[serde(rename = "_meta")]
5528    pub meta: Option<Meta>,
5529}
5530
5531impl AgentCapabilities {
5532    /// Builds an empty [`AgentCapabilities`]. Use builder methods to advertise supported sub-capabilities.
5533    #[must_use]
5534    pub fn new() -> Self {
5535        Self::default()
5536    }
5537
5538    /// Whether the agent supports `session/load`.
5539    #[must_use]
5540    pub fn load_session(mut self, load_session: bool) -> Self {
5541        self.load_session = load_session;
5542        self
5543    }
5544
5545    /// Prompt capabilities supported by the agent.
5546    #[must_use]
5547    pub fn prompt_capabilities(mut self, prompt_capabilities: PromptCapabilities) -> Self {
5548        self.prompt_capabilities = prompt_capabilities;
5549        self
5550    }
5551
5552    /// MCP capabilities supported by the agent.
5553    #[must_use]
5554    pub fn mcp_capabilities(mut self, mcp_capabilities: McpCapabilities) -> Self {
5555        self.mcp_capabilities = mcp_capabilities;
5556        self
5557    }
5558
5559    /// Session capabilities supported by the agent.
5560    #[must_use]
5561    pub fn session_capabilities(mut self, session_capabilities: SessionCapabilities) -> Self {
5562        self.session_capabilities = session_capabilities;
5563        self
5564    }
5565
5566    /// Authentication-related capabilities supported by the agent.
5567    #[must_use]
5568    pub fn auth(mut self, auth: AgentAuthCapabilities) -> Self {
5569        self.auth = auth;
5570        self
5571    }
5572
5573    /// **UNSTABLE**
5574    ///
5575    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5576    ///
5577    /// Provider configuration capabilities supported by the agent.
5578    #[cfg(feature = "unstable_llm_providers")]
5579    #[must_use]
5580    pub fn providers(mut self, providers: impl IntoOption<ProvidersCapabilities>) -> Self {
5581        self.providers = providers.into_option();
5582        self
5583    }
5584
5585    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5586    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5587    /// these keys.
5588    ///
5589    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5590    #[must_use]
5591    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5592        self.meta = meta.into_option();
5593        self
5594    }
5595}
5596
5597/// **UNSTABLE**
5598///
5599/// This capability is not part of the spec yet, and may be removed or changed at any point.
5600///
5601/// Provider configuration capabilities supported by the agent.
5602///
5603/// Supplying `{}` means the agent supports provider configuration methods.
5604#[cfg(feature = "unstable_llm_providers")]
5605#[serde_as]
5606#[skip_serializing_none]
5607#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5608#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
5609#[non_exhaustive]
5610pub struct ProvidersCapabilities {
5611    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5612    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5613    /// these keys.
5614    ///
5615    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5616    #[serde_as(deserialize_as = "DefaultOnError")]
5617    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5618    #[serde(default)]
5619    #[serde(rename = "_meta")]
5620    pub meta: Option<Meta>,
5621}
5622
5623#[cfg(feature = "unstable_llm_providers")]
5624impl ProvidersCapabilities {
5625    /// Builds an empty [`ProvidersCapabilities`]. Use builder methods to advertise supported sub-capabilities.
5626    #[must_use]
5627    pub fn new() -> Self {
5628        Self::default()
5629    }
5630
5631    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5632    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5633    /// these keys.
5634    ///
5635    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5636    #[must_use]
5637    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5638        self.meta = meta.into_option();
5639        self
5640    }
5641}
5642
5643/// Session capabilities supported by the agent.
5644///
5645/// As a baseline, all Agents **MUST** support `session/new`, `session/prompt`, `session/cancel`, and `session/update`.
5646///
5647/// Optionally, they **MAY** support other session methods and notifications by specifying additional capabilities.
5648///
5649/// Note: `session/load` is still handled by the top-level `loadSession` capability. This will be unified in future versions of the protocol.
5650///
5651/// See protocol docs: [Session Capabilities](https://agentclientprotocol.com/protocol/v1/initialization#session-capabilities)
5652#[serde_as]
5653#[skip_serializing_none]
5654#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5655#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
5656#[serde(rename_all = "camelCase")]
5657#[non_exhaustive]
5658pub struct SessionCapabilities {
5659    /// Whether the agent supports `session/list`.
5660    ///
5661    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5662    /// Supplying `{}` means the agent supports listing sessions.
5663    #[serde_as(deserialize_as = "DefaultOnError")]
5664    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5665    #[serde(default)]
5666    pub list: Option<SessionListCapabilities>,
5667    /// Whether the agent supports `session/delete`.
5668    ///
5669    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5670    /// Supplying `{}` means the agent supports deleting sessions from `session/list`.
5671    #[serde_as(deserialize_as = "DefaultOnError")]
5672    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5673    #[serde(default)]
5674    pub delete: Option<SessionDeleteCapabilities>,
5675    /// Whether the agent supports `additionalDirectories` on supported session lifecycle requests.
5676    ///
5677    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5678    /// Supplying `{}` means the agent supports `additionalDirectories` on
5679    /// supported session lifecycle requests.
5680    ///
5681    /// Agents that also support `session/list` may return
5682    /// `SessionInfo.additionalDirectories` to report the complete ordered
5683    /// additional-root list associated with a listed session.
5684    #[serde_as(deserialize_as = "DefaultOnError")]
5685    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5686    #[serde(default)]
5687    pub additional_directories: Option<SessionAdditionalDirectoriesCapabilities>,
5688    /// Whether the agent supports `systemPrompt` on session lifecycle requests.
5689    ///
5690    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5691    /// Supplying `{}` means the agent supports `systemPrompt` in `append` mode.
5692    #[serde_as(deserialize_as = "DefaultOnError")]
5693    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5694    #[serde(default)]
5695    pub system_prompt: Option<SessionSystemPromptCapabilities>,
5696    /// **UNSTABLE**
5697    ///
5698    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5699    ///
5700    /// Whether the agent supports `session/fork`.
5701    ///
5702    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5703    /// Supplying `{}` means the agent supports forking sessions.
5704    #[cfg(feature = "unstable_session_fork")]
5705    #[serde_as(deserialize_as = "DefaultOnError")]
5706    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5707    #[serde(default)]
5708    pub fork: Option<SessionForkCapabilities>,
5709    /// **UNSTABLE**
5710    ///
5711    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5712    ///
5713    /// Whether the agent supports `session/archive` and `session/unarchive`.
5714    ///
5715    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5716    /// Supplying `{}` means the agent supports both methods, the `archived` filter on
5717    /// `session/list`, and `SessionInfo.archived`. Agents that advertise it MUST also advertise `sessionCapabilities.list`.
5718    #[cfg(feature = "unstable_session_archive")]
5719    #[serde_as(deserialize_as = "DefaultOnError")]
5720    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5721    #[serde(default)]
5722    pub archive: Option<SessionArchiveCapabilities>,
5723    /// **UNSTABLE**
5724    ///
5725    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5726    ///
5727    /// Whether the agent supports `session/status`.
5728    ///
5729    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5730    /// Supplying `{}` means the agent supports checking session status.
5731    #[cfg(feature = "unstable_session_status")]
5732    #[serde_as(deserialize_as = "DefaultOnError")]
5733    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5734    #[serde(default)]
5735    pub status: Option<SessionStatusCapabilities>,
5736    /// **UNSTABLE**
5737    ///
5738    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5739    ///
5740    /// Whether the agent supports `session/options`.
5741    ///
5742    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5743    /// Supplying `{}` means the agent supports `session/options` and accepts initial
5744    /// config option values on session setup requests.
5745    #[cfg(feature = "unstable_session_options")]
5746    #[serde_as(deserialize_as = "DefaultOnError")]
5747    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5748    #[serde(default)]
5749    pub options: Option<SessionOptionsCapabilities>,
5750    /// **UNSTABLE**
5751    ///
5752    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5753    ///
5754    /// Whether the agent supports `session/set_title`.
5755    ///
5756    /// Agents report titles through `session/list` and `session_info_update` without this
5757    /// capability. It only advertises that Clients can set titles.
5758    ///
5759    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5760    /// Supplying `{}` means the agent supports setting session titles.
5761    #[cfg(feature = "unstable_session_set_title")]
5762    #[serde_as(deserialize_as = "DefaultOnError")]
5763    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5764    #[serde(default)]
5765    pub title: Option<SessionTitleCapabilities>,
5766    /// Whether the agent supports `session/resume`.
5767    ///
5768    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5769    /// Supplying `{}` means the agent supports resuming sessions.
5770    #[serde_as(deserialize_as = "DefaultOnError")]
5771    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5772    #[serde(default)]
5773    pub resume: Option<SessionResumeCapabilities>,
5774    /// Whether the agent supports `session/close`.
5775    ///
5776    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5777    /// Supplying `{}` means the agent supports closing sessions.
5778    #[serde_as(deserialize_as = "DefaultOnError")]
5779    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5780    #[serde(default)]
5781    pub close: Option<SessionCloseCapabilities>,
5782    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5783    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5784    /// these keys.
5785    ///
5786    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5787    #[serde_as(deserialize_as = "DefaultOnError")]
5788    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5789    #[serde(default)]
5790    #[serde(rename = "_meta")]
5791    pub meta: Option<Meta>,
5792}
5793
5794impl SessionCapabilities {
5795    /// Builds an empty [`SessionCapabilities`]. Use builder methods to advertise supported sub-capabilities.
5796    #[must_use]
5797    pub fn new() -> Self {
5798        Self::default()
5799    }
5800
5801    /// Whether the agent supports `session/list`.
5802    ///
5803    /// Omitted or `null` both mean the agent does not advertise support.
5804    /// Supplying `{}` means the agent supports listing sessions.
5805    #[must_use]
5806    pub fn list(mut self, list: impl IntoOption<SessionListCapabilities>) -> Self {
5807        self.list = list.into_option();
5808        self
5809    }
5810
5811    /// Whether the agent supports `session/delete`.
5812    ///
5813    /// Omitted or `null` both mean the agent does not advertise support.
5814    /// Supplying `{}` means the agent supports deleting sessions from `session/list`.
5815    #[must_use]
5816    pub fn delete(mut self, delete: impl IntoOption<SessionDeleteCapabilities>) -> Self {
5817        self.delete = delete.into_option();
5818        self
5819    }
5820
5821    /// Whether the agent supports `additionalDirectories` on supported session lifecycle requests.
5822    ///
5823    /// Omitted or `null` both mean the agent does not advertise support.
5824    /// Supplying `{}` means the agent supports `additionalDirectories` on
5825    /// supported session lifecycle requests.
5826    ///
5827    /// Agents that also support `session/list` may return
5828    /// `SessionInfo.additionalDirectories` to report the complete ordered
5829    /// additional-root list associated with a listed session.
5830    #[must_use]
5831    pub fn additional_directories(
5832        mut self,
5833        additional_directories: impl IntoOption<SessionAdditionalDirectoriesCapabilities>,
5834    ) -> Self {
5835        self.additional_directories = additional_directories.into_option();
5836        self
5837    }
5838
5839    /// Whether the agent supports `systemPrompt` on session lifecycle requests.
5840    ///
5841    /// Omitted or `null` both mean the agent does not advertise support.
5842    /// Supplying `{}` means the agent supports `systemPrompt` in `append` mode.
5843    #[must_use]
5844    pub fn system_prompt(
5845        mut self,
5846        system_prompt: impl IntoOption<SessionSystemPromptCapabilities>,
5847    ) -> Self {
5848        self.system_prompt = system_prompt.into_option();
5849        self
5850    }
5851
5852    #[cfg(feature = "unstable_session_fork")]
5853    /// Whether the agent supports `session/fork`.
5854    ///
5855    /// Omitted or `null` both mean the agent does not advertise support.
5856    /// Supplying `{}` means the agent supports forking sessions.
5857    #[must_use]
5858    pub fn fork(mut self, fork: impl IntoOption<SessionForkCapabilities>) -> Self {
5859        self.fork = fork.into_option();
5860        self
5861    }
5862
5863    /// **UNSTABLE**
5864    ///
5865    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5866    ///
5867    /// Whether the agent supports `session/archive` and `session/unarchive`.
5868    ///
5869    /// Omitted or `null` both mean the agent does not advertise support.
5870    /// Supplying `{}` means the agent supports both methods, the `archived` filter on
5871    /// `session/list`, and `SessionInfo.archived`.
5872    #[cfg(feature = "unstable_session_archive")]
5873    #[must_use]
5874    pub fn archive(mut self, archive: impl IntoOption<SessionArchiveCapabilities>) -> Self {
5875        self.archive = archive.into_option();
5876        self
5877    }
5878
5879    /// **UNSTABLE**
5880    ///
5881    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5882    ///
5883    /// Whether the agent supports `session/status`.
5884    ///
5885    /// Omitted or `null` both mean the agent does not advertise support.
5886    /// Supplying `{}` means the agent supports checking session status.
5887    #[cfg(feature = "unstable_session_status")]
5888    #[must_use]
5889    pub fn status(mut self, status: impl IntoOption<SessionStatusCapabilities>) -> Self {
5890        self.status = status.into_option();
5891        self
5892    }
5893
5894    /// **UNSTABLE**
5895    ///
5896    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5897    ///
5898    /// Whether the agent supports `session/options`.
5899    ///
5900    /// Omitted or `null` both mean the agent does not advertise support.
5901    /// Supplying `{}` means the agent supports `session/options` and accepts initial
5902    /// config option values on session setup requests.
5903    #[cfg(feature = "unstable_session_options")]
5904    #[must_use]
5905    pub fn options(mut self, options: impl IntoOption<SessionOptionsCapabilities>) -> Self {
5906        self.options = options.into_option();
5907        self
5908    }
5909
5910    /// **UNSTABLE**
5911    ///
5912    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5913    ///
5914    /// Whether the agent supports `session/set_title`.
5915    ///
5916    /// Agents report titles through `session/list` and `session_info_update` without this
5917    /// capability. It only advertises that Clients can set titles.
5918    ///
5919    /// Omitted or `null` both mean the agent does not advertise support.
5920    /// Supplying `{}` means the agent supports setting session titles.
5921    #[cfg(feature = "unstable_session_set_title")]
5922    #[must_use]
5923    pub fn title(mut self, title: impl IntoOption<SessionTitleCapabilities>) -> Self {
5924        self.title = title.into_option();
5925        self
5926    }
5927
5928    /// Whether the agent supports `session/resume`.
5929    ///
5930    /// Omitted or `null` both mean the agent does not advertise support.
5931    /// Supplying `{}` means the agent supports resuming sessions.
5932    #[must_use]
5933    pub fn resume(mut self, resume: impl IntoOption<SessionResumeCapabilities>) -> Self {
5934        self.resume = resume.into_option();
5935        self
5936    }
5937
5938    /// Whether the agent supports `session/close`.
5939    ///
5940    /// Omitted or `null` both mean the agent does not advertise support.
5941    /// Supplying `{}` means the agent supports closing sessions.
5942    #[must_use]
5943    pub fn close(mut self, close: impl IntoOption<SessionCloseCapabilities>) -> Self {
5944        self.close = close.into_option();
5945        self
5946    }
5947
5948    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5949    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5950    /// these keys.
5951    ///
5952    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5953    #[must_use]
5954    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5955        self.meta = meta.into_option();
5956        self
5957    }
5958}
5959
5960/// Capabilities for the `session/list` method.
5961///
5962/// Supplying `{}` means the agent supports listing sessions.
5963#[serde_as]
5964#[skip_serializing_none]
5965#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5966#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
5967#[non_exhaustive]
5968pub struct SessionListCapabilities {
5969    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5970    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5971    /// these keys.
5972    ///
5973    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5974    #[serde_as(deserialize_as = "DefaultOnError")]
5975    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5976    #[serde(default)]
5977    #[serde(rename = "_meta")]
5978    pub meta: Option<Meta>,
5979}
5980
5981impl SessionListCapabilities {
5982    /// Builds an empty [`SessionListCapabilities`]. Use builder methods to advertise supported sub-capabilities.
5983    #[must_use]
5984    pub fn new() -> Self {
5985        Self::default()
5986    }
5987
5988    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5989    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5990    /// these keys.
5991    ///
5992    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5993    #[must_use]
5994    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5995        self.meta = meta.into_option();
5996        self
5997    }
5998}
5999
6000/// Capabilities for the `session/delete` method.
6001///
6002/// Supplying `{}` means the agent supports deleting sessions from `session/list`.
6003#[serde_as]
6004#[skip_serializing_none]
6005#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6006#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6007#[non_exhaustive]
6008pub struct SessionDeleteCapabilities {
6009    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6010    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6011    /// these keys.
6012    ///
6013    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6014    #[serde_as(deserialize_as = "DefaultOnError")]
6015    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6016    #[serde(default)]
6017    #[serde(rename = "_meta")]
6018    pub meta: Option<Meta>,
6019}
6020
6021impl SessionDeleteCapabilities {
6022    /// Builds an empty [`SessionDeleteCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6023    #[must_use]
6024    pub fn new() -> Self {
6025        Self::default()
6026    }
6027
6028    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6029    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6030    /// these keys.
6031    ///
6032    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6033    #[must_use]
6034    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6035        self.meta = meta.into_option();
6036        self
6037    }
6038}
6039
6040/// Capabilities for additional session directories support.
6041///
6042/// Supplying `{}` means the agent supports the `additionalDirectories` field on
6043/// supported session lifecycle requests. Agents that also support
6044/// `session/list` may return `SessionInfo.additionalDirectories` to report the
6045/// complete ordered additional-root list associated with a listed session.
6046#[serde_as]
6047#[skip_serializing_none]
6048#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6049#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6050#[non_exhaustive]
6051pub struct SessionAdditionalDirectoriesCapabilities {
6052    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6053    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6054    /// these keys.
6055    ///
6056    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6057    #[serde_as(deserialize_as = "DefaultOnError")]
6058    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6059    #[serde(default)]
6060    #[serde(rename = "_meta")]
6061    pub meta: Option<Meta>,
6062}
6063
6064impl SessionAdditionalDirectoriesCapabilities {
6065    /// Builds an empty [`SessionAdditionalDirectoriesCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6066    #[must_use]
6067    pub fn new() -> Self {
6068        Self::default()
6069    }
6070
6071    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6072    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6073    /// these keys.
6074    ///
6075    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6076    #[must_use]
6077    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6078        self.meta = meta.into_option();
6079        self
6080    }
6081}
6082
6083/// Capabilities for client-provided system prompts.
6084///
6085/// Supplying `{}` means the agent supports `systemPrompt` on session lifecycle
6086/// requests in `append` mode.
6087#[serde_as]
6088#[skip_serializing_none]
6089#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6090#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6091#[serde(rename_all = "camelCase")]
6092#[non_exhaustive]
6093pub struct SessionSystemPromptCapabilities {
6094    /// Delivery modes the agent supports in addition to `append`.
6095    ///
6096    /// Optional. Omitted or `null` both mean the agent supports only `append`.
6097    #[serde_as(deserialize_as = "DefaultOnError")]
6098    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6099    #[serde(default)]
6100    pub mode: Option<SessionSystemPromptModeCapabilities>,
6101    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6102    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6103    /// these keys.
6104    ///
6105    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6106    #[serde_as(deserialize_as = "DefaultOnError")]
6107    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6108    #[serde(default)]
6109    #[serde(rename = "_meta")]
6110    pub meta: Option<Meta>,
6111}
6112
6113impl SessionSystemPromptCapabilities {
6114    /// Builds an empty [`SessionSystemPromptCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6115    #[must_use]
6116    pub fn new() -> Self {
6117        Self::default()
6118    }
6119
6120    /// Delivery modes the agent supports in addition to `append`.
6121    ///
6122    /// Omitted or `null` both mean the agent supports only `append`.
6123    #[must_use]
6124    pub fn mode(mut self, mode: impl IntoOption<SessionSystemPromptModeCapabilities>) -> Self {
6125        self.mode = mode.into_option();
6126        self
6127    }
6128
6129    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6130    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6131    /// these keys.
6132    ///
6133    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6134    #[must_use]
6135    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6136        self.meta = meta.into_option();
6137        self
6138    }
6139}
6140
6141/// System prompt delivery modes the agent supports in addition to `append`.
6142///
6143/// `append` has no entry because every agent advertising
6144/// `sessionCapabilities.systemPrompt` supports it.
6145#[serde_as]
6146#[skip_serializing_none]
6147#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6148#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6149#[serde(rename_all = "camelCase")]
6150#[non_exhaustive]
6151pub struct SessionSystemPromptModeCapabilities {
6152    /// Whether the agent supports `override` mode.
6153    ///
6154    /// Optional. Omitted or `null` both mean the agent does not advertise support.
6155    /// Supplying `{}` means the agent supports replacing its built-in default
6156    /// instructions with the client-provided system prompt.
6157    #[serde_as(deserialize_as = "DefaultOnError")]
6158    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6159    #[serde(default, rename = "override")]
6160    pub override_: Option<SessionSystemPromptOverrideCapabilities>,
6161    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6162    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6163    /// these keys.
6164    ///
6165    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6166    #[serde_as(deserialize_as = "DefaultOnError")]
6167    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6168    #[serde(default)]
6169    #[serde(rename = "_meta")]
6170    pub meta: Option<Meta>,
6171}
6172
6173impl SessionSystemPromptModeCapabilities {
6174    /// Builds an empty [`SessionSystemPromptModeCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6175    #[must_use]
6176    pub fn new() -> Self {
6177        Self::default()
6178    }
6179
6180    /// Whether the agent supports `override` mode.
6181    ///
6182    /// Omitted or `null` both mean the agent does not advertise support.
6183    /// Supplying `{}` means the agent supports replacing its built-in default
6184    /// instructions with the client-provided system prompt.
6185    #[must_use]
6186    pub fn override_(
6187        mut self,
6188        override_: impl IntoOption<SessionSystemPromptOverrideCapabilities>,
6189    ) -> Self {
6190        self.override_ = override_.into_option();
6191        self
6192    }
6193
6194    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6195    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6196    /// these keys.
6197    ///
6198    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6199    #[must_use]
6200    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6201        self.meta = meta.into_option();
6202        self
6203    }
6204}
6205
6206/// Capabilities for the `override` system prompt mode.
6207///
6208/// Supplying `{}` means the agent supports replacing its built-in default
6209/// instructions with the client-provided system prompt.
6210#[serde_as]
6211#[skip_serializing_none]
6212#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6213#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6214#[non_exhaustive]
6215pub struct SessionSystemPromptOverrideCapabilities {
6216    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6217    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6218    /// these keys.
6219    ///
6220    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6221    #[serde_as(deserialize_as = "DefaultOnError")]
6222    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6223    #[serde(default)]
6224    #[serde(rename = "_meta")]
6225    pub meta: Option<Meta>,
6226}
6227
6228impl SessionSystemPromptOverrideCapabilities {
6229    /// Builds an empty [`SessionSystemPromptOverrideCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6230    #[must_use]
6231    pub fn new() -> Self {
6232        Self::default()
6233    }
6234
6235    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6236    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6237    /// these keys.
6238    ///
6239    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6240    #[must_use]
6241    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6242        self.meta = meta.into_option();
6243        self
6244    }
6245}
6246
6247/// **UNSTABLE**
6248///
6249/// This capability is not part of the spec yet, and may be removed or changed at any point.
6250///
6251/// Capabilities for the `session/fork` method.
6252///
6253/// Supplying `{}` means the agent supports forking sessions.
6254#[cfg(feature = "unstable_session_fork")]
6255#[serde_as]
6256#[skip_serializing_none]
6257#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6258#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6259#[non_exhaustive]
6260pub struct SessionForkCapabilities {
6261    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6262    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6263    /// these keys.
6264    ///
6265    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6266    #[serde_as(deserialize_as = "DefaultOnError")]
6267    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6268    #[serde(default)]
6269    #[serde(rename = "_meta")]
6270    pub meta: Option<Meta>,
6271}
6272
6273#[cfg(feature = "unstable_session_fork")]
6274impl SessionForkCapabilities {
6275    /// Builds an empty [`SessionForkCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6276    #[must_use]
6277    pub fn new() -> Self {
6278        Self::default()
6279    }
6280
6281    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6282    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6283    /// these keys.
6284    ///
6285    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6286    #[must_use]
6287    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6288        self.meta = meta.into_option();
6289        self
6290    }
6291}
6292
6293/// **UNSTABLE**
6294///
6295/// This capability is not part of the spec yet, and may be removed or changed at any point.
6296///
6297/// Capabilities for `session/archive` and `session/unarchive`.
6298///
6299/// Supplying `{}` means the agent supports both methods, the `archived` filter on
6300/// `session/list`, and `SessionInfo.archived`.
6301#[cfg(feature = "unstable_session_archive")]
6302#[serde_as]
6303#[skip_serializing_none]
6304#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6305#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6306#[non_exhaustive]
6307pub struct SessionArchiveCapabilities {
6308    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6309    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6310    /// these keys.
6311    ///
6312    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6313    #[serde_as(deserialize_as = "DefaultOnError")]
6314    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6315    #[serde(default)]
6316    #[serde(rename = "_meta")]
6317    pub meta: Option<Meta>,
6318}
6319
6320#[cfg(feature = "unstable_session_archive")]
6321impl SessionArchiveCapabilities {
6322    /// Builds an empty [`SessionArchiveCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6323    #[must_use]
6324    pub fn new() -> Self {
6325        Self::default()
6326    }
6327
6328    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6329    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6330    /// these keys.
6331    ///
6332    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6333    #[must_use]
6334    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6335        self.meta = meta.into_option();
6336        self
6337    }
6338}
6339
6340/// **UNSTABLE**
6341///
6342/// This capability is not part of the spec yet, and may be removed or changed at any point.
6343///
6344/// Capabilities for the `session/status` method.
6345///
6346/// Supplying `{}` means the agent supports checking session status.
6347#[cfg(feature = "unstable_session_status")]
6348#[serde_as]
6349#[skip_serializing_none]
6350#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6351#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6352#[non_exhaustive]
6353pub struct SessionStatusCapabilities {
6354    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6355    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6356    /// these keys.
6357    ///
6358    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6359    #[serde_as(deserialize_as = "DefaultOnError")]
6360    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6361    #[serde(default)]
6362    #[serde(rename = "_meta")]
6363    pub meta: Option<Meta>,
6364}
6365
6366#[cfg(feature = "unstable_session_status")]
6367impl SessionStatusCapabilities {
6368    /// Builds an empty [`SessionStatusCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6369    #[must_use]
6370    pub fn new() -> Self {
6371        Self::default()
6372    }
6373
6374    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6375    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6376    /// these keys.
6377    ///
6378    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6379    #[must_use]
6380    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6381        self.meta = meta.into_option();
6382        self
6383    }
6384}
6385
6386/// **UNSTABLE**
6387///
6388/// This capability is not part of the spec yet, and may be removed or changed at any point.
6389///
6390/// Capabilities for the `session/options` method.
6391///
6392/// Supplying `{}` means the agent supports `session/options` and accepts initial config
6393/// option values on session setup requests.
6394#[cfg(feature = "unstable_session_options")]
6395#[serde_as]
6396#[skip_serializing_none]
6397#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6398#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6399#[non_exhaustive]
6400pub struct SessionOptionsCapabilities {
6401    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6402    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6403    /// these keys.
6404    ///
6405    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6406    #[serde_as(deserialize_as = "DefaultOnError")]
6407    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6408    #[serde(default)]
6409    #[serde(rename = "_meta")]
6410    pub meta: Option<Meta>,
6411}
6412
6413#[cfg(feature = "unstable_session_options")]
6414impl SessionOptionsCapabilities {
6415    /// Builds an empty [`SessionOptionsCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6416    #[must_use]
6417    pub fn new() -> Self {
6418        Self::default()
6419    }
6420
6421    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6422    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6423    /// these keys.
6424    ///
6425    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6426    #[must_use]
6427    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6428        self.meta = meta.into_option();
6429        self
6430    }
6431}
6432
6433/// **UNSTABLE**
6434///
6435/// This capability is not part of the spec yet, and may be removed or changed at any point.
6436///
6437/// Capabilities for Client-set session titles.
6438///
6439/// Supplying `{}` means the agent supports `session/set_title`. Agents report titles
6440/// through `session/list` and `session_info_update` without this capability.
6441#[cfg(feature = "unstable_session_set_title")]
6442#[serde_as]
6443#[skip_serializing_none]
6444#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6445#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6446#[non_exhaustive]
6447pub struct SessionTitleCapabilities {
6448    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6449    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6450    /// these keys.
6451    ///
6452    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6453    #[serde_as(deserialize_as = "DefaultOnError")]
6454    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6455    #[serde(default)]
6456    #[serde(rename = "_meta")]
6457    pub meta: Option<Meta>,
6458}
6459
6460#[cfg(feature = "unstable_session_set_title")]
6461impl SessionTitleCapabilities {
6462    /// Builds an empty [`SessionTitleCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6463    #[must_use]
6464    pub fn new() -> Self {
6465        Self::default()
6466    }
6467
6468    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6469    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6470    /// these keys.
6471    ///
6472    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6473    #[must_use]
6474    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6475        self.meta = meta.into_option();
6476        self
6477    }
6478}
6479
6480/// Capabilities for the `session/resume` method.
6481///
6482/// Supplying `{}` means the agent supports resuming sessions.
6483#[serde_as]
6484#[skip_serializing_none]
6485#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6486#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6487#[non_exhaustive]
6488pub struct SessionResumeCapabilities {
6489    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6490    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6491    /// these keys.
6492    ///
6493    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6494    #[serde_as(deserialize_as = "DefaultOnError")]
6495    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6496    #[serde(default)]
6497    #[serde(rename = "_meta")]
6498    pub meta: Option<Meta>,
6499}
6500
6501impl SessionResumeCapabilities {
6502    /// Builds an empty [`SessionResumeCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6503    #[must_use]
6504    pub fn new() -> Self {
6505        Self::default()
6506    }
6507
6508    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6509    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6510    /// these keys.
6511    ///
6512    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6513    #[must_use]
6514    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6515        self.meta = meta.into_option();
6516        self
6517    }
6518}
6519
6520/// Capabilities for the `session/close` method.
6521///
6522/// Supplying `{}` means the agent supports closing sessions.
6523#[serde_as]
6524#[skip_serializing_none]
6525#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6526#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6527#[non_exhaustive]
6528pub struct SessionCloseCapabilities {
6529    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6530    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6531    /// these keys.
6532    ///
6533    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6534    #[serde_as(deserialize_as = "DefaultOnError")]
6535    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6536    #[serde(default)]
6537    #[serde(rename = "_meta")]
6538    pub meta: Option<Meta>,
6539}
6540
6541impl SessionCloseCapabilities {
6542    /// Builds an empty [`SessionCloseCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6543    #[must_use]
6544    pub fn new() -> Self {
6545        Self::default()
6546    }
6547
6548    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6549    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6550    /// these keys.
6551    ///
6552    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6553    #[must_use]
6554    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6555        self.meta = meta.into_option();
6556        self
6557    }
6558}
6559
6560/// Prompt capabilities supported by the agent in `session/prompt` requests.
6561///
6562/// Baseline agent functionality requires support for `text`
6563/// and `resource_link` content blocks in prompt requests.
6564///
6565/// Other variants must be explicitly opted in to.
6566/// Capabilities for different types of content in prompt requests.
6567///
6568/// Indicates which content types beyond the baseline (text and resource links)
6569/// the agent can process.
6570///
6571/// See protocol docs: [Prompt Capabilities](https://agentclientprotocol.com/protocol/v1/initialization#prompt-capabilities)
6572#[serde_as]
6573#[skip_serializing_none]
6574#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6575#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6576#[serde(rename_all = "camelCase")]
6577#[non_exhaustive]
6578pub struct PromptCapabilities {
6579    /// Agent supports `image` content blocks.
6580    #[serde_as(deserialize_as = "DefaultOnError")]
6581    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6582    #[serde(default)]
6583    pub image: bool,
6584    /// Agent supports `audio` content blocks.
6585    #[serde_as(deserialize_as = "DefaultOnError")]
6586    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6587    #[serde(default)]
6588    pub audio: bool,
6589    /// Agent supports embedded context in `session/prompt` requests.
6590    ///
6591    /// When enabled, the Client is allowed to include `resource` content blocks
6592    /// in prompt requests for pieces of context that are referenced in the message.
6593    #[serde_as(deserialize_as = "DefaultOnError")]
6594    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6595    #[serde(default)]
6596    pub embedded_context: bool,
6597    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6598    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6599    /// these keys.
6600    ///
6601    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6602    #[serde_as(deserialize_as = "DefaultOnError")]
6603    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6604    #[serde(default)]
6605    #[serde(rename = "_meta")]
6606    pub meta: Option<Meta>,
6607}
6608
6609impl PromptCapabilities {
6610    /// Builds an empty [`PromptCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6611    #[must_use]
6612    pub fn new() -> Self {
6613        Self::default()
6614    }
6615
6616    /// Agent supports `image` content blocks.
6617    #[must_use]
6618    pub fn image(mut self, image: bool) -> Self {
6619        self.image = image;
6620        self
6621    }
6622
6623    /// Agent supports `audio` content blocks.
6624    #[must_use]
6625    pub fn audio(mut self, audio: bool) -> Self {
6626        self.audio = audio;
6627        self
6628    }
6629
6630    /// Agent supports embedded context in `session/prompt` requests.
6631    ///
6632    /// When enabled, the Client is allowed to include `resource` content blocks
6633    /// in prompt requests for pieces of context that are referenced in the message.
6634    #[must_use]
6635    pub fn embedded_context(mut self, embedded_context: bool) -> Self {
6636        self.embedded_context = embedded_context;
6637        self
6638    }
6639
6640    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6641    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6642    /// these keys.
6643    ///
6644    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6645    #[must_use]
6646    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6647        self.meta = meta.into_option();
6648        self
6649    }
6650}
6651
6652/// MCP capabilities supported by the agent
6653#[serde_as]
6654#[skip_serializing_none]
6655#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6656#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6657#[serde(rename_all = "camelCase")]
6658#[non_exhaustive]
6659pub struct McpCapabilities {
6660    /// Agent supports `http` MCP servers.
6661    #[serde_as(deserialize_as = "DefaultOnError")]
6662    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6663    #[serde(default)]
6664    pub http: bool,
6665    /// Agent supports `sse` MCP servers.
6666    #[serde_as(deserialize_as = "DefaultOnError")]
6667    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6668    #[serde(default)]
6669    pub sse: bool,
6670    /// **UNSTABLE**
6671    ///
6672    /// This capability is not part of the spec yet, and may be removed or changed at any point.
6673    ///
6674    /// Agent supports `acp` MCP servers.
6675    #[cfg(feature = "unstable_mcp_over_acp")]
6676    #[serde_as(deserialize_as = "DefaultOnError")]
6677    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6678    #[serde(default)]
6679    pub acp: bool,
6680    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6681    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6682    /// these keys.
6683    ///
6684    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6685    #[serde_as(deserialize_as = "DefaultOnError")]
6686    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6687    #[serde(default)]
6688    #[serde(rename = "_meta")]
6689    pub meta: Option<Meta>,
6690}
6691
6692impl McpCapabilities {
6693    /// Builds an empty [`McpCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6694    #[must_use]
6695    pub fn new() -> Self {
6696        Self::default()
6697    }
6698
6699    /// Agent supports `http` MCP servers.
6700    #[must_use]
6701    pub fn http(mut self, http: bool) -> Self {
6702        self.http = http;
6703        self
6704    }
6705
6706    /// Agent supports `sse` MCP servers.
6707    #[must_use]
6708    pub fn sse(mut self, sse: bool) -> Self {
6709        self.sse = sse;
6710        self
6711    }
6712
6713    /// **UNSTABLE**
6714    ///
6715    /// This capability is not part of the spec yet, and may be removed or changed at any point.
6716    ///
6717    /// Agent supports `acp` MCP servers.
6718    #[cfg(feature = "unstable_mcp_over_acp")]
6719    #[must_use]
6720    pub fn acp(mut self, acp: bool) -> Self {
6721        self.acp = acp;
6722        self
6723    }
6724
6725    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6726    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6727    /// these keys.
6728    ///
6729    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6730    #[must_use]
6731    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6732        self.meta = meta.into_option();
6733        self
6734    }
6735}
6736
6737// Method schema
6738
6739/// Names of all methods that agents handle.
6740///
6741/// Provides a centralized definition of method names used in the protocol.
6742#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6743#[non_exhaustive]
6744pub struct AgentMethodNames {
6745    /// Method for initializing the connection.
6746    pub initialize: &'static str,
6747    /// Method for authenticating with the agent.
6748    pub authenticate: &'static str,
6749    /// Method for listing configurable providers.
6750    #[cfg(feature = "unstable_llm_providers")]
6751    pub providers_list: &'static str,
6752    /// Method for setting provider configuration.
6753    #[cfg(feature = "unstable_llm_providers")]
6754    pub providers_set: &'static str,
6755    /// Method for disabling a provider.
6756    #[cfg(feature = "unstable_llm_providers")]
6757    pub providers_disable: &'static str,
6758    /// Method for creating a new session.
6759    pub session_new: &'static str,
6760    /// Method for loading an existing session.
6761    pub session_load: &'static str,
6762    /// Method for setting the mode for a session.
6763    pub session_set_mode: &'static str,
6764    /// Method for setting a configuration option for a session.
6765    pub session_set_config_option: &'static str,
6766    /// Method for sending a prompt to the agent.
6767    pub session_prompt: &'static str,
6768    /// Notification for cancelling operations.
6769    pub session_cancel: &'static str,
6770    /// Method for exchanging MCP-over-ACP messages.
6771    #[cfg(feature = "unstable_mcp_over_acp")]
6772    pub mcp_message: &'static str,
6773    /// Method for listing existing sessions.
6774    pub session_list: &'static str,
6775    /// Method for deleting an existing session.
6776    pub session_delete: &'static str,
6777    /// Method for forking an existing session.
6778    #[cfg(feature = "unstable_session_fork")]
6779    pub session_fork: &'static str,
6780    /// Method for archiving a session.
6781    #[cfg(feature = "unstable_session_archive")]
6782    pub session_archive: &'static str,
6783    /// Method for unarchiving a session.
6784    #[cfg(feature = "unstable_session_archive")]
6785    pub session_unarchive: &'static str,
6786    /// Method for checking the status of a session.
6787    #[cfg(feature = "unstable_session_status")]
6788    pub session_status: &'static str,
6789    /// Method for querying the config options a session would start with.
6790    #[cfg(feature = "unstable_session_options")]
6791    pub session_options: &'static str,
6792    /// Method for setting the title of a session.
6793    #[cfg(feature = "unstable_session_set_title")]
6794    pub session_set_title: &'static str,
6795    /// Method for resuming an existing session.
6796    pub session_resume: &'static str,
6797    /// Method for closing an active session.
6798    pub session_close: &'static str,
6799    /// Method for logging out of an authenticated session.
6800    pub logout: &'static str,
6801    /// Method for querying the agent's authentication state.
6802    #[cfg(feature = "unstable_auth_status")]
6803    pub auth_status: &'static str,
6804}
6805
6806/// Constant containing all agent method names.
6807pub const AGENT_METHOD_NAMES: AgentMethodNames = AgentMethodNames {
6808    initialize: INITIALIZE_METHOD_NAME,
6809    authenticate: AUTHENTICATE_METHOD_NAME,
6810    #[cfg(feature = "unstable_llm_providers")]
6811    providers_list: PROVIDERS_LIST_METHOD_NAME,
6812    #[cfg(feature = "unstable_llm_providers")]
6813    providers_set: PROVIDERS_SET_METHOD_NAME,
6814    #[cfg(feature = "unstable_llm_providers")]
6815    providers_disable: PROVIDERS_DISABLE_METHOD_NAME,
6816    session_new: SESSION_NEW_METHOD_NAME,
6817    session_load: SESSION_LOAD_METHOD_NAME,
6818    session_set_mode: SESSION_SET_MODE_METHOD_NAME,
6819    session_set_config_option: SESSION_SET_CONFIG_OPTION_METHOD_NAME,
6820    session_prompt: SESSION_PROMPT_METHOD_NAME,
6821    session_cancel: SESSION_CANCEL_METHOD_NAME,
6822    #[cfg(feature = "unstable_mcp_over_acp")]
6823    mcp_message: MCP_MESSAGE_METHOD_NAME,
6824    session_list: SESSION_LIST_METHOD_NAME,
6825    session_delete: SESSION_DELETE_METHOD_NAME,
6826    #[cfg(feature = "unstable_session_fork")]
6827    session_fork: SESSION_FORK_METHOD_NAME,
6828    #[cfg(feature = "unstable_session_archive")]
6829    session_archive: SESSION_ARCHIVE_METHOD_NAME,
6830    #[cfg(feature = "unstable_session_archive")]
6831    session_unarchive: SESSION_UNARCHIVE_METHOD_NAME,
6832    #[cfg(feature = "unstable_session_status")]
6833    session_status: SESSION_STATUS_METHOD_NAME,
6834    #[cfg(feature = "unstable_session_options")]
6835    session_options: SESSION_OPTIONS_METHOD_NAME,
6836    #[cfg(feature = "unstable_session_set_title")]
6837    session_set_title: SESSION_SET_TITLE_METHOD_NAME,
6838    session_resume: SESSION_RESUME_METHOD_NAME,
6839    session_close: SESSION_CLOSE_METHOD_NAME,
6840    logout: LOGOUT_METHOD_NAME,
6841    #[cfg(feature = "unstable_auth_status")]
6842    auth_status: AUTH_STATUS_METHOD_NAME,
6843};
6844
6845/// Method name for the initialize request.
6846pub(crate) const INITIALIZE_METHOD_NAME: &str = "initialize";
6847/// Method name for the authenticate request.
6848pub(crate) const AUTHENTICATE_METHOD_NAME: &str = "authenticate";
6849/// Method name for listing configurable providers.
6850#[cfg(feature = "unstable_llm_providers")]
6851pub(crate) const PROVIDERS_LIST_METHOD_NAME: &str = "providers/list";
6852/// Method name for setting provider configuration.
6853#[cfg(feature = "unstable_llm_providers")]
6854pub(crate) const PROVIDERS_SET_METHOD_NAME: &str = "providers/set";
6855/// Method name for disabling a provider.
6856#[cfg(feature = "unstable_llm_providers")]
6857pub(crate) const PROVIDERS_DISABLE_METHOD_NAME: &str = "providers/disable";
6858/// Method name for creating a new session.
6859pub(crate) const SESSION_NEW_METHOD_NAME: &str = "session/new";
6860/// Method name for loading an existing session.
6861pub(crate) const SESSION_LOAD_METHOD_NAME: &str = "session/load";
6862/// Method name for setting the mode for a session.
6863pub(crate) const SESSION_SET_MODE_METHOD_NAME: &str = "session/set_mode";
6864/// Method name for setting a configuration option for a session.
6865pub(crate) const SESSION_SET_CONFIG_OPTION_METHOD_NAME: &str = "session/set_config_option";
6866/// Method name for sending a prompt.
6867pub(crate) const SESSION_PROMPT_METHOD_NAME: &str = "session/prompt";
6868/// Method name for the cancel notification.
6869pub(crate) const SESSION_CANCEL_METHOD_NAME: &str = "session/cancel";
6870/// Method name for listing existing sessions.
6871pub(crate) const SESSION_LIST_METHOD_NAME: &str = "session/list";
6872/// Method name for deleting an existing session.
6873pub(crate) const SESSION_DELETE_METHOD_NAME: &str = "session/delete";
6874/// Method name for forking an existing session.
6875#[cfg(feature = "unstable_session_fork")]
6876pub(crate) const SESSION_FORK_METHOD_NAME: &str = "session/fork";
6877/// Method name for archiving a session.
6878#[cfg(feature = "unstable_session_archive")]
6879pub(crate) const SESSION_ARCHIVE_METHOD_NAME: &str = "session/archive";
6880/// Method name for unarchiving a session.
6881#[cfg(feature = "unstable_session_archive")]
6882pub(crate) const SESSION_UNARCHIVE_METHOD_NAME: &str = "session/unarchive";
6883/// Method name for checking the status of a session.
6884#[cfg(feature = "unstable_session_status")]
6885pub(crate) const SESSION_STATUS_METHOD_NAME: &str = "session/status";
6886/// Method name for querying the config options a session would start with.
6887#[cfg(feature = "unstable_session_options")]
6888pub(crate) const SESSION_OPTIONS_METHOD_NAME: &str = "session/options";
6889/// Method name for setting the title of a session.
6890#[cfg(feature = "unstable_session_set_title")]
6891pub(crate) const SESSION_SET_TITLE_METHOD_NAME: &str = "session/set_title";
6892/// Method name for resuming an existing session.
6893pub(crate) const SESSION_RESUME_METHOD_NAME: &str = "session/resume";
6894/// Method name for closing an active session.
6895pub(crate) const SESSION_CLOSE_METHOD_NAME: &str = "session/close";
6896/// Method name for logging out of an authenticated session.
6897pub(crate) const LOGOUT_METHOD_NAME: &str = "logout";
6898/// Method name for the `auth/status` request.
6899#[cfg(feature = "unstable_auth_status")]
6900pub(crate) const AUTH_STATUS_METHOD_NAME: &str = "auth/status";
6901
6902/// All possible requests that a client can send to an agent.
6903///
6904/// This enum is used internally for routing RPC requests. You typically won't need
6905/// to use this directly.
6906///
6907/// This enum encompasses all method calls from client to agent.
6908#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6909#[derive(Clone, Debug, Serialize, Deserialize)]
6910#[serde(untagged)]
6911#[cfg_attr(feature = "schemars", schemars(inline))]
6912#[non_exhaustive]
6913#[expect(
6914    clippy::large_enum_variant,
6915    reason = "TODO(next major): box InitializeRequest in the v1 enum"
6916)]
6917pub enum ClientRequest {
6918    /// Establishes the connection with a client and negotiates protocol capabilities.
6919    ///
6920    /// This method is called once at the beginning of the connection to:
6921    /// - Negotiate the protocol version to use
6922    /// - Exchange capability information between client and agent
6923    /// - Determine available authentication methods
6924    ///
6925    /// The agent should respond with its supported protocol version and capabilities.
6926    ///
6927    /// See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/v1/initialization)
6928    InitializeRequest(InitializeRequest),
6929    /// Authenticates the client using the specified authentication method.
6930    ///
6931    /// Called when the agent requires authentication before allowing session creation.
6932    /// The client provides an authentication method ID that was advertised during
6933    /// initialization and whose type defines the `authenticate` flow.
6934    ///
6935    /// After successful authentication, the client can proceed to create sessions with
6936    /// `session/new` without receiving an `auth_required` (`-32000`) error.
6937    ///
6938    /// See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/v1/initialization)
6939    AuthenticateRequest(AuthenticateRequest),
6940    /// **UNSTABLE**
6941    ///
6942    /// This capability is not part of the spec yet, and may be removed or changed at any point.
6943    ///
6944    /// Lists providers that can be configured by the client.
6945    #[cfg(feature = "unstable_llm_providers")]
6946    ListProvidersRequest(ListProvidersRequest),
6947    /// **UNSTABLE**
6948    ///
6949    /// This capability is not part of the spec yet, and may be removed or changed at any point.
6950    ///
6951    /// Replaces the configuration for a provider.
6952    #[cfg(feature = "unstable_llm_providers")]
6953    SetProviderRequest(SetProviderRequest),
6954    /// **UNSTABLE**
6955    ///
6956    /// This capability is not part of the spec yet, and may be removed or changed at any point.
6957    ///
6958    /// Disables a provider.
6959    #[cfg(feature = "unstable_llm_providers")]
6960    DisableProviderRequest(DisableProviderRequest),
6961    /// Logs out of the current authenticated state.
6962    ///
6963    /// After a successful logout, all new sessions will require authentication.
6964    /// There is no guarantee about the behavior of already running sessions.
6965    LogoutRequest(LogoutRequest),
6966    /// **UNSTABLE**
6967    ///
6968    /// This capability is not part of the spec yet, and may be removed or changed at any point.
6969    ///
6970    /// Queries the agent's current authentication state.
6971    ///
6972    /// This method is only available if the agent advertises the `auth.status` capability.
6973    /// It MUST NOT change any agent state, and agents MUST NOT reject it with `auth_required`.
6974    #[cfg(feature = "unstable_auth_status")]
6975    AuthStatusRequest(AuthStatusRequest),
6976    /// Creates a new conversation session with the agent.
6977    ///
6978    /// Sessions represent independent conversation contexts with their own history and state.
6979    ///
6980    /// The agent should:
6981    /// - Create a new session context
6982    /// - Connect to any specified MCP servers
6983    /// - Return a unique session ID for future requests
6984    ///
6985    /// May return an `auth_required` (`-32000`) error if the agent requires authentication.
6986    ///
6987    /// See protocol docs: [Session Setup](https://agentclientprotocol.com/protocol/v1/session-setup)
6988    NewSessionRequest(NewSessionRequest),
6989    /// Loads an existing session to resume a previous conversation.
6990    ///
6991    /// This method is only available if the agent advertises the `loadSession` capability.
6992    ///
6993    /// The agent should:
6994    /// - Restore the session context and conversation history
6995    /// - Connect to the specified MCP servers
6996    /// - Stream the entire conversation history back to the client via notifications
6997    ///
6998    /// See protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/v1/session-setup#loading-sessions)
6999    LoadSessionRequest(LoadSessionRequest),
7000    /// Lists existing sessions known to the agent.
7001    ///
7002    /// This method is only available if the agent advertises the `sessionCapabilities.list` capability.
7003    ///
7004    /// The agent should return metadata about sessions with optional filtering and pagination support.
7005    ListSessionsRequest(ListSessionsRequest),
7006    /// Deletes an existing session from `session/list`.
7007    ///
7008    /// This method is only available if the agent advertises the `sessionCapabilities.delete` capability.
7009    DeleteSessionRequest(DeleteSessionRequest),
7010    #[cfg(feature = "unstable_session_fork")]
7011    /// **UNSTABLE**
7012    ///
7013    /// This capability is not part of the spec yet, and may be removed or changed at any point.
7014    ///
7015    /// Forks an existing session to create a new independent session.
7016    ///
7017    /// This method is only available if the agent advertises the `session.fork` capability.
7018    ///
7019    /// The agent should create a new session with the same conversation context as the
7020    /// original, allowing operations like generating summaries without affecting the
7021    /// original session's history.
7022    ///
7023    /// As with `session/new`, the forked session is active once the agent responds,
7024    /// set up with the request's `cwd`, `additionalDirectories`, and `mcpServers`.
7025    /// The client can prompt it without calling `session/load` or `session/resume` first.
7026    ForkSessionRequest(ForkSessionRequest),
7027    #[cfg(feature = "unstable_session_archive")]
7028    /// **UNSTABLE**
7029    ///
7030    /// This capability is not part of the spec yet, and may be removed or changed at any point.
7031    ///
7032    /// Archives a session, hiding it from default `session/list` results.
7033    ///
7034    /// This method is only available if the agent advertises the `sessionCapabilities.archive` capability.
7035    ArchiveSessionRequest(ArchiveSessionRequest),
7036    #[cfg(feature = "unstable_session_archive")]
7037    /// **UNSTABLE**
7038    ///
7039    /// This capability is not part of the spec yet, and may be removed or changed at any point.
7040    ///
7041    /// Unarchives a session, returning it to default `session/list` results.
7042    ///
7043    /// This method is only available if the agent advertises the `sessionCapabilities.archive` capability.
7044    UnarchiveSessionRequest(UnarchiveSessionRequest),
7045    #[cfg(feature = "unstable_session_status")]
7046    /// **UNSTABLE**
7047    ///
7048    /// This capability is not part of the spec yet, and may be removed or changed at any point.
7049    ///
7050    /// Checks whether the Agent has a session in memory, without changing it.
7051    ///
7052    /// This method is only available if the agent advertises the `sessionCapabilities.status` capability.
7053    SessionStatusRequest(SessionStatusRequest),
7054    #[cfg(feature = "unstable_session_options")]
7055    /// **UNSTABLE**
7056    ///
7057    /// This capability is not part of the spec yet, and may be removed or changed at any point.
7058    ///
7059    /// Returns the config options a session would start with, without creating or resuming a session.
7060    ///
7061    /// This method is only available if the agent advertises the `sessionCapabilities.options` capability.
7062    SessionOptionsRequest(SessionOptionsRequest),
7063    #[cfg(feature = "unstable_session_set_title")]
7064    /// **UNSTABLE**
7065    ///
7066    /// This capability is not part of the spec yet, and may be removed or changed at any point.
7067    ///
7068    /// Sets the title of a session.
7069    ///
7070    /// This method is only available if the agent advertises the `sessionCapabilities.title` capability.
7071    ///
7072    /// The session does not need to be active on the connection. The agent stores the
7073    /// title and returns the stored title, which may be normalized.
7074    SetSessionTitleRequest(SetSessionTitleRequest),
7075    /// Resumes an existing session without returning previous messages.
7076    ///
7077    /// This method is only available if the agent advertises the `sessionCapabilities.resume` capability.
7078    ///
7079    /// The agent should resume the session context, allowing the conversation to continue
7080    /// without replaying the message history (unlike `session/load`).
7081    ResumeSessionRequest(ResumeSessionRequest),
7082    /// Closes an active session and frees up any resources associated with it.
7083    ///
7084    /// This method is only available if the agent advertises the `sessionCapabilities.close` capability.
7085    ///
7086    /// The agent MUST cancel any ongoing work (as if `session/cancel` was called)
7087    /// and then free up any resources associated with the session.
7088    CloseSessionRequest(CloseSessionRequest),
7089    /// Sets the current mode for a session.
7090    ///
7091    /// Allows switching between different agent modes (e.g., "ask", "architect", "code")
7092    /// that affect system prompts, tool availability, and permission behaviors.
7093    ///
7094    /// The mode MUST be one of the modes advertised in `availableModes` during session
7095    /// creation or loading. Agents may also change modes autonomously and notify the
7096    /// client via `current_mode_update` notifications.
7097    ///
7098    /// This method can be called at any time during a session, whether the Agent is
7099    /// idle or actively generating a response.
7100    ///
7101    /// See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/session-modes)
7102    SetSessionModeRequest(SetSessionModeRequest),
7103    /// Sets the current value for a session configuration option.
7104    SetSessionConfigOptionRequest(SetSessionConfigOptionRequest),
7105    /// Processes a user prompt within a session.
7106    ///
7107    /// This method handles the whole lifecycle of a prompt:
7108    /// - Receives user messages with optional context (files, images, etc.)
7109    /// - Processes the prompt using language models
7110    /// - Reports language model content and tool calls to the Clients
7111    /// - Requests permission to run tools
7112    /// - Executes any requested tool calls
7113    /// - Returns when the turn is complete with a stop reason
7114    ///
7115    /// See protocol docs: [Prompt Turn](https://agentclientprotocol.com/protocol/v1/prompt-turn)
7116    PromptRequest(PromptRequest),
7117    /// Handles extension method requests from the client.
7118    ///
7119    /// Extension methods provide a way to add custom functionality while maintaining
7120    /// protocol compatibility.
7121    ///
7122    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
7123    ExtMethodRequest(ExtRequest),
7124}
7125
7126impl_request_dispatch! {
7127    ClientRequest => AgentResponse {
7128        InitializeRequest => InitializeResponse: AGENT_METHOD_NAMES.initialize,
7129        AuthenticateRequest => AuthenticateResponse: AGENT_METHOD_NAMES.authenticate,
7130        #[cfg(feature = "unstable_llm_providers")]
7131        ListProvidersRequest => ListProvidersResponse: AGENT_METHOD_NAMES.providers_list,
7132        #[cfg(feature = "unstable_llm_providers")]
7133        SetProviderRequest => SetProviderResponse: AGENT_METHOD_NAMES.providers_set,
7134        #[cfg(feature = "unstable_llm_providers")]
7135        DisableProviderRequest => DisableProviderResponse: AGENT_METHOD_NAMES.providers_disable,
7136        LogoutRequest => LogoutResponse: AGENT_METHOD_NAMES.logout,
7137        #[cfg(feature = "unstable_auth_status")]
7138        AuthStatusRequest => AuthStatusResponse: AGENT_METHOD_NAMES.auth_status,
7139        NewSessionRequest => NewSessionResponse: AGENT_METHOD_NAMES.session_new,
7140        LoadSessionRequest => LoadSessionResponse: AGENT_METHOD_NAMES.session_load,
7141        ListSessionsRequest => ListSessionsResponse: AGENT_METHOD_NAMES.session_list,
7142        DeleteSessionRequest => DeleteSessionResponse: AGENT_METHOD_NAMES.session_delete,
7143        #[cfg(feature = "unstable_session_fork")]
7144        ForkSessionRequest => ForkSessionResponse: AGENT_METHOD_NAMES.session_fork,
7145        #[cfg(feature = "unstable_session_archive")]
7146        ArchiveSessionRequest => ArchiveSessionResponse: AGENT_METHOD_NAMES.session_archive,
7147        #[cfg(feature = "unstable_session_archive")]
7148        UnarchiveSessionRequest => UnarchiveSessionResponse: AGENT_METHOD_NAMES.session_unarchive,
7149        #[cfg(feature = "unstable_session_status")]
7150        SessionStatusRequest => SessionStatusResponse: AGENT_METHOD_NAMES.session_status,
7151        #[cfg(feature = "unstable_session_options")]
7152        SessionOptionsRequest => SessionOptionsResponse: AGENT_METHOD_NAMES.session_options,
7153        #[cfg(feature = "unstable_session_set_title")]
7154        SetSessionTitleRequest => SetSessionTitleResponse: AGENT_METHOD_NAMES.session_set_title,
7155        ResumeSessionRequest => ResumeSessionResponse: AGENT_METHOD_NAMES.session_resume,
7156        CloseSessionRequest => CloseSessionResponse: AGENT_METHOD_NAMES.session_close,
7157        SetSessionModeRequest => SetSessionModeResponse: AGENT_METHOD_NAMES.session_set_mode,
7158        SetSessionConfigOptionRequest => SetSessionConfigOptionResponse: AGENT_METHOD_NAMES.session_set_config_option,
7159        PromptRequest => PromptResponse: AGENT_METHOD_NAMES.session_prompt,
7160    }
7161    extension ExtMethodRequest(ExtRequest) => ExtMethodResponse;
7162}
7163
7164/// All possible responses that an agent can send to a client.
7165///
7166/// This enum is used internally for routing RPC responses. You typically won't need
7167/// to use this directly - the responses are handled automatically by the connection.
7168///
7169/// These are responses to the corresponding `ClientRequest` variants.
7170#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
7171#[derive(Clone, Debug, Serialize, Deserialize)]
7172#[serde(untagged)]
7173#[cfg_attr(feature = "schemars", schemars(inline))]
7174#[non_exhaustive]
7175#[expect(
7176    clippy::large_enum_variant,
7177    reason = "TODO(next major): box InitializeResponse in the v1 enum"
7178)]
7179pub enum AgentResponse {
7180    /// Successful result returned for a `initialize` request.
7181    InitializeResponse(InitializeResponse),
7182    /// Successful result returned for a `authenticate` request.
7183    AuthenticateResponse(#[serde(default)] AuthenticateResponse),
7184    /// Successful result returned for a `providers/list` request.
7185    #[cfg(feature = "unstable_llm_providers")]
7186    ListProvidersResponse(ListProvidersResponse),
7187    /// Successful result returned for a `providers/set` request.
7188    #[cfg(feature = "unstable_llm_providers")]
7189    SetProviderResponse(#[serde(default)] SetProviderResponse),
7190    /// Successful result returned for a `providers/disable` request.
7191    #[cfg(feature = "unstable_llm_providers")]
7192    DisableProviderResponse(#[serde(default)] DisableProviderResponse),
7193    /// Successful result returned for a `logout` request.
7194    LogoutResponse(#[serde(default)] LogoutResponse),
7195    /// Successful result returned for an `auth/status` request.
7196    #[cfg(feature = "unstable_auth_status")]
7197    AuthStatusResponse(AuthStatusResponse),
7198    /// Successful result returned for a `session/new` request.
7199    NewSessionResponse(NewSessionResponse),
7200    /// Successful result returned for a `session/load` request.
7201    LoadSessionResponse(#[serde(default)] LoadSessionResponse),
7202    /// Successful result returned for a `session/list` request.
7203    ListSessionsResponse(ListSessionsResponse),
7204    /// Successful result returned for a `session/delete` request.
7205    DeleteSessionResponse(#[serde(default)] DeleteSessionResponse),
7206    /// Successful result returned for a `session/fork` request.
7207    #[cfg(feature = "unstable_session_fork")]
7208    ForkSessionResponse(ForkSessionResponse),
7209    /// Successful result returned for a `session/archive` request.
7210    #[cfg(feature = "unstable_session_archive")]
7211    ArchiveSessionResponse(#[serde(default)] ArchiveSessionResponse),
7212    /// Successful result returned for a `session/unarchive` request.
7213    #[cfg(feature = "unstable_session_archive")]
7214    UnarchiveSessionResponse(#[serde(default)] UnarchiveSessionResponse),
7215    /// Successful result returned for a `session/status` request.
7216    #[cfg(feature = "unstable_session_status")]
7217    SessionStatusResponse(SessionStatusResponse),
7218    /// Successful result returned for a `session/options` request.
7219    #[cfg(feature = "unstable_session_options")]
7220    SessionOptionsResponse(#[serde(default)] SessionOptionsResponse),
7221    /// Successful result returned for a `session/set_title` request.
7222    #[cfg(feature = "unstable_session_set_title")]
7223    SetSessionTitleResponse(SetSessionTitleResponse),
7224    /// Successful result returned for a `session/resume` request.
7225    ResumeSessionResponse(#[serde(default)] ResumeSessionResponse),
7226    /// Successful result returned for a `session/close` request.
7227    CloseSessionResponse(#[serde(default)] CloseSessionResponse),
7228    /// Successful result returned for a `session/set_mode` request.
7229    SetSessionModeResponse(#[serde(default)] SetSessionModeResponse),
7230    /// Successful result returned for a `session/set_config_option` request.
7231    SetSessionConfigOptionResponse(SetSessionConfigOptionResponse),
7232    /// Successful result returned for a `session/prompt` request.
7233    PromptResponse(PromptResponse),
7234    /// Successful result returned by an extension method outside the core ACP method set.
7235    ExtMethodResponse(ExtResponse),
7236}
7237
7238/// All possible notifications that a client can send to an agent.
7239///
7240/// This enum is used internally for routing RPC notifications. You typically won't need
7241/// to use this directly.
7242///
7243/// Notifications do not expect a response.
7244#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
7245#[derive(Clone, Debug, Serialize, Deserialize)]
7246#[serde(untagged)]
7247#[cfg_attr(feature = "schemars", schemars(inline))]
7248#[non_exhaustive]
7249pub enum ClientNotification {
7250    /// Cancels ongoing operations for a session.
7251    ///
7252    /// This is a notification sent by the client to cancel an ongoing prompt turn.
7253    ///
7254    /// Upon receiving this notification, the Agent SHOULD:
7255    /// - Stop all language model requests as soon as possible
7256    /// - Abort all tool call invocations in progress
7257    /// - Send any pending `session/update` notifications
7258    /// - Respond to the original `session/prompt` request with the `cancelled` stop reason
7259    ///
7260    /// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v1/prompt-turn#cancellation)
7261    CancelNotification(CancelNotification),
7262    /// **UNSTABLE**
7263    ///
7264    /// This capability is not part of the spec yet, and may be removed or changed at any point.
7265    ///
7266    /// Sends an MCP-over-ACP notification.
7267    #[cfg(feature = "unstable_mcp_over_acp")]
7268    MessageMcpNotification(MessageMcpNotification),
7269    /// Handles extension notifications from the client.
7270    ///
7271    /// Extension notifications provide a way to send one-way messages for custom functionality
7272    /// while maintaining protocol compatibility.
7273    ///
7274    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
7275    ExtNotification(ExtNotification),
7276}
7277
7278impl_message_dispatch! {
7279    ClientNotification {
7280        CancelNotification => AGENT_METHOD_NAMES.session_cancel,
7281        #[cfg(feature = "unstable_mcp_over_acp")]
7282        MessageMcpNotification => AGENT_METHOD_NAMES.mcp_message,
7283    }
7284    extension ExtNotification(ExtNotification);
7285}
7286
7287/// Notification to cancel ongoing operations for a session.
7288///
7289/// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v1/prompt-turn#cancellation)
7290#[serde_as]
7291#[skip_serializing_none]
7292#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
7293#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
7294#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_CANCEL_METHOD_NAME)))]
7295#[serde(rename_all = "camelCase")]
7296#[non_exhaustive]
7297pub struct CancelNotification {
7298    /// The ID of the session to cancel operations for.
7299    pub session_id: SessionId,
7300    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
7301    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
7302    /// these keys.
7303    ///
7304    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
7305    #[serde_as(deserialize_as = "DefaultOnError")]
7306    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
7307    #[serde(default)]
7308    #[serde(rename = "_meta")]
7309    pub meta: Option<Meta>,
7310}
7311
7312impl CancelNotification {
7313    /// Builds [`CancelNotification`] with the required notification fields set. Optional fields start unset or empty.
7314    #[must_use]
7315    pub fn new(session_id: impl Into<SessionId>) -> Self {
7316        Self {
7317            session_id: session_id.into(),
7318            meta: None,
7319        }
7320    }
7321
7322    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
7323    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
7324    /// these keys.
7325    ///
7326    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
7327    #[must_use]
7328    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
7329        self.meta = meta.into_option();
7330        self
7331    }
7332}
7333
7334#[cfg(test)]
7335mod test_serialization {
7336    use super::*;
7337    use serde_json::json;
7338
7339    fn test_meta() -> Meta {
7340        json!({ "source": "test" }).as_object().unwrap().clone()
7341    }
7342
7343    fn serialized_meta_key_count(value: &impl serde::Serialize) -> usize {
7344        serde_json::to_string(value)
7345            .unwrap()
7346            .matches("\"_meta\"")
7347            .count()
7348    }
7349
7350    /// v1 reports prompt failures as JSON-RPC errors. Only the subagent
7351    /// snapshot has an `error` stop reason, because a child has no prompt response.
7352    #[test]
7353    fn prompt_response_has_no_error_stop_reason() {
7354        assert_eq!(
7355            serde_json::from_value::<PromptResponse>(json!({ "stopReason": "end_turn" }))
7356                .unwrap()
7357                .stop_reason,
7358            StopReason::EndTurn
7359        );
7360        assert!(
7361            serde_json::from_value::<PromptResponse>(json!({ "stopReason": "error" })).is_err()
7362        );
7363    }
7364
7365    #[test]
7366    fn test_initialize_capabilities_default_on_malformed_values() {
7367        let request: InitializeRequest = serde_json::from_value(json!({
7368            "protocolVersion": 1,
7369            "clientCapabilities": false
7370        }))
7371        .unwrap();
7372        assert_eq!(request.client_capabilities, ClientCapabilities::default());
7373
7374        let response: InitializeResponse = serde_json::from_value(json!({
7375            "protocolVersion": 1,
7376            "agentCapabilities": false
7377        }))
7378        .unwrap();
7379        assert_eq!(response.agent_capabilities, AgentCapabilities::default());
7380    }
7381
7382    #[test]
7383    fn test_agent_capabilities_default_on_malformed_values() {
7384        let capabilities: AgentCapabilities = serde_json::from_value(json!({
7385            "loadSession": "yes",
7386            "promptCapabilities": {
7387                "image": "yes",
7388                "audio": true,
7389                "embeddedContext": {}
7390            },
7391            "mcpCapabilities": {
7392                "http": "yes",
7393                "sse": true
7394            },
7395            "sessionCapabilities": false,
7396            "auth": false
7397        }))
7398        .unwrap();
7399
7400        assert!(!capabilities.load_session);
7401        assert!(!capabilities.prompt_capabilities.image);
7402        assert!(capabilities.prompt_capabilities.audio);
7403        assert!(!capabilities.prompt_capabilities.embedded_context);
7404        assert!(!capabilities.mcp_capabilities.http);
7405        assert!(capabilities.mcp_capabilities.sse);
7406        assert_eq!(
7407            capabilities.session_capabilities,
7408            SessionCapabilities::default()
7409        );
7410        assert_eq!(capabilities.auth, AgentAuthCapabilities::default());
7411    }
7412
7413    #[test]
7414    fn test_mcp_server_stdio_serialization() {
7415        let server = McpServer::Stdio(
7416            McpServerStdio::new("test-server", "/usr/bin/server")
7417                .args(vec!["--port".to_string(), "3000".to_string()])
7418                .env(vec![EnvVariable::new("API_KEY", "secret123")]),
7419        );
7420
7421        let json = serde_json::to_value(&server).unwrap();
7422        assert_eq!(
7423            json,
7424            json!({
7425                "name": "test-server",
7426                "command": "/usr/bin/server",
7427                "args": ["--port", "3000"],
7428                "env": [
7429                    {
7430                        "name": "API_KEY",
7431                        "value": "secret123"
7432                    }
7433                ]
7434            })
7435        );
7436
7437        let deserialized: McpServer = serde_json::from_value(json).unwrap();
7438        match deserialized {
7439            McpServer::Stdio(McpServerStdio {
7440                name,
7441                command,
7442                args,
7443                env,
7444                meta: _,
7445            }) => {
7446                assert_eq!(name, "test-server");
7447                assert_eq!(command, PathBuf::from("/usr/bin/server"));
7448                assert_eq!(args, vec!["--port", "3000"]);
7449                assert_eq!(env.len(), 1);
7450                assert_eq!(env[0].name, "API_KEY");
7451                assert_eq!(env[0].value, "secret123");
7452            }
7453            _ => panic!("Expected Stdio variant"),
7454        }
7455    }
7456
7457    #[test]
7458    fn test_mcp_server_http_serialization() {
7459        let server = McpServer::Http(
7460            McpServerHttp::new("http-server", "https://api.example.com").headers(vec![
7461                HttpHeader::new("Authorization", "Bearer token123"),
7462                HttpHeader::new("Content-Type", "application/json"),
7463            ]),
7464        );
7465
7466        let json = serde_json::to_value(&server).unwrap();
7467        assert_eq!(
7468            json,
7469            json!({
7470                "type": "http",
7471                "name": "http-server",
7472                "url": "https://api.example.com",
7473                "headers": [
7474                    {
7475                        "name": "Authorization",
7476                        "value": "Bearer token123"
7477                    },
7478                    {
7479                        "name": "Content-Type",
7480                        "value": "application/json"
7481                    }
7482                ]
7483            })
7484        );
7485
7486        let deserialized: McpServer = serde_json::from_value(json).unwrap();
7487        match deserialized {
7488            McpServer::Http(McpServerHttp {
7489                name,
7490                url,
7491                headers,
7492                meta: _,
7493            }) => {
7494                assert_eq!(name, "http-server");
7495                assert_eq!(url, "https://api.example.com");
7496                assert_eq!(headers.len(), 2);
7497                assert_eq!(headers[0].name, "Authorization");
7498                assert_eq!(headers[0].value, "Bearer token123");
7499                assert_eq!(headers[1].name, "Content-Type");
7500                assert_eq!(headers[1].value, "application/json");
7501            }
7502            _ => panic!("Expected Http variant"),
7503        }
7504    }
7505
7506    #[cfg(feature = "unstable_mcp_over_acp")]
7507    #[test]
7508    fn test_mcp_server_acp_serialization() {
7509        let server = McpServer::Acp(McpServerAcp::new("project-tools", "project-tools-id"));
7510
7511        let json = serde_json::to_value(&server).unwrap();
7512        assert_eq!(
7513            json,
7514            json!({
7515                "type": "acp",
7516                "name": "project-tools",
7517                "serverId": "project-tools-id"
7518            })
7519        );
7520
7521        let deserialized: McpServer = serde_json::from_value(json).unwrap();
7522        match deserialized {
7523            McpServer::Acp(McpServerAcp {
7524                name,
7525                server_id: id,
7526                meta: _,
7527            }) => {
7528                assert_eq!(name, "project-tools");
7529                assert_eq!(id, McpServerAcpId::new("project-tools-id"));
7530            }
7531            _ => panic!("Expected Acp variant"),
7532        }
7533    }
7534
7535    #[cfg(feature = "unstable_mcp_over_acp")]
7536    #[test]
7537    fn test_client_mcp_message_method_names() {
7538        use serde_json::json;
7539
7540        assert_eq!(AGENT_METHOD_NAMES.mcp_message, "mcp/message");
7541
7542        let notification =
7543            MessageMcpNotification::new("server-1", "req-1", "notifications/progress");
7544        assert_eq!(
7545            ClientNotification::MessageMcpNotification(notification.clone()).method(),
7546            "mcp/message"
7547        );
7548        assert_eq!(
7549            serde_json::to_value(notification).unwrap(),
7550            json!({
7551                "serverId": "server-1",
7552                "requestId": "req-1",
7553                "method": "notifications/progress"
7554            })
7555        );
7556        let notification: MessageMcpNotification = serde_json::from_value(json!({
7557            "serverId": "server-1", "requestId": "req-1", "method": "notifications/progress",
7558            "params": null, "_meta": null
7559        }))
7560        .unwrap();
7561        assert_eq!(notification.params, None);
7562        assert_eq!(notification.meta, None);
7563        for key in ["serverId", "requestId", "method"] {
7564            let mut value = json!({"serverId":"server-1", "requestId":"req-1", "method":"notifications/progress"});
7565            value.as_object_mut().unwrap().remove(key);
7566            assert!(serde_json::from_value::<MessageMcpNotification>(value).is_err());
7567        }
7568    }
7569
7570    #[cfg(all(feature = "unstable_mcp_over_acp", feature = "schemars"))]
7571    #[test]
7572    fn test_mcp_server_acp_schema() {
7573        let mcp_server_schema = serde_json::to_value(schemars::schema_for!(McpServer)).unwrap();
7574        assert!(json_contains_entry(
7575            &mcp_server_schema,
7576            "const",
7577            &json!("acp")
7578        ));
7579        assert!(json_contains_entry(
7580            &mcp_server_schema,
7581            "$ref",
7582            &json!("#/$defs/McpServerAcp")
7583        ));
7584
7585        let capabilities_schema =
7586            serde_json::to_value(schemars::schema_for!(McpCapabilities)).unwrap();
7587        assert!(json_contains_key(&capabilities_schema, "acp"));
7588    }
7589
7590    #[cfg(all(feature = "unstable_mcp_over_acp", feature = "schemars"))]
7591    fn json_contains_entry(
7592        value: &serde_json::Value,
7593        key: &str,
7594        expected: &serde_json::Value,
7595    ) -> bool {
7596        match value {
7597            serde_json::Value::Object(map) => {
7598                map.get(key) == Some(expected)
7599                    || map
7600                        .values()
7601                        .any(|value| json_contains_entry(value, key, expected))
7602            }
7603            serde_json::Value::Array(values) => values
7604                .iter()
7605                .any(|value| json_contains_entry(value, key, expected)),
7606            _ => false,
7607        }
7608    }
7609
7610    #[cfg(all(feature = "unstable_mcp_over_acp", feature = "schemars"))]
7611    fn json_contains_key(value: &serde_json::Value, key: &str) -> bool {
7612        match value {
7613            serde_json::Value::Object(map) => {
7614                map.contains_key(key) || map.values().any(|value| json_contains_key(value, key))
7615            }
7616            serde_json::Value::Array(values) => {
7617                values.iter().any(|value| json_contains_key(value, key))
7618            }
7619            _ => false,
7620        }
7621    }
7622
7623    #[test]
7624    fn test_mcp_server_sse_serialization() {
7625        let server = McpServer::Sse(
7626            McpServerSse::new("sse-server", "https://sse.example.com/events")
7627                .headers(vec![HttpHeader::new("X-API-Key", "apikey456")]),
7628        );
7629
7630        let json = serde_json::to_value(&server).unwrap();
7631        assert_eq!(
7632            json,
7633            json!({
7634                "type": "sse",
7635                "name": "sse-server",
7636                "url": "https://sse.example.com/events",
7637                "headers": [
7638                    {
7639                        "name": "X-API-Key",
7640                        "value": "apikey456"
7641                    }
7642                ]
7643            })
7644        );
7645
7646        let deserialized: McpServer = serde_json::from_value(json).unwrap();
7647        match deserialized {
7648            McpServer::Sse(McpServerSse {
7649                name,
7650                url,
7651                headers,
7652                meta: _,
7653            }) => {
7654                assert_eq!(name, "sse-server");
7655                assert_eq!(url, "https://sse.example.com/events");
7656                assert_eq!(headers.len(), 1);
7657                assert_eq!(headers[0].name, "X-API-Key");
7658                assert_eq!(headers[0].value, "apikey456");
7659            }
7660            _ => panic!("Expected Sse variant"),
7661        }
7662    }
7663
7664    #[test]
7665    fn test_session_config_option_category_known_variants() {
7666        // Test serialization of known variants
7667        assert_eq!(
7668            serde_json::to_value(&SessionConfigOptionCategory::Mode).unwrap(),
7669            json!("mode")
7670        );
7671        assert_eq!(
7672            serde_json::to_value(&SessionConfigOptionCategory::Model).unwrap(),
7673            json!("model")
7674        );
7675        assert_eq!(
7676            serde_json::to_value(&SessionConfigOptionCategory::ModelConfig).unwrap(),
7677            json!("model_config")
7678        );
7679        #[cfg(feature = "unstable_speed_config_category")]
7680        assert_eq!(
7681            serde_json::to_value(&SessionConfigOptionCategory::Speed).unwrap(),
7682            json!("speed")
7683        );
7684        assert_eq!(
7685            serde_json::to_value(&SessionConfigOptionCategory::ThoughtLevel).unwrap(),
7686            json!("thought_level")
7687        );
7688
7689        // Test deserialization of known variants
7690        assert_eq!(
7691            serde_json::from_str::<SessionConfigOptionCategory>("\"mode\"").unwrap(),
7692            SessionConfigOptionCategory::Mode
7693        );
7694        assert_eq!(
7695            serde_json::from_str::<SessionConfigOptionCategory>("\"model\"").unwrap(),
7696            SessionConfigOptionCategory::Model
7697        );
7698        assert_eq!(
7699            serde_json::from_str::<SessionConfigOptionCategory>("\"model_config\"").unwrap(),
7700            SessionConfigOptionCategory::ModelConfig
7701        );
7702        #[cfg(feature = "unstable_speed_config_category")]
7703        assert_eq!(
7704            serde_json::from_str::<SessionConfigOptionCategory>("\"speed\"").unwrap(),
7705            SessionConfigOptionCategory::Speed
7706        );
7707        assert_eq!(
7708            serde_json::from_str::<SessionConfigOptionCategory>("\"thought_level\"").unwrap(),
7709            SessionConfigOptionCategory::ThoughtLevel
7710        );
7711    }
7712
7713    #[test]
7714    fn test_session_config_option_category_unknown_variants() {
7715        // Test that unknown strings are captured in Other variant
7716        let unknown: SessionConfigOptionCategory =
7717            serde_json::from_str("\"some_future_category\"").unwrap();
7718        assert_eq!(
7719            unknown,
7720            SessionConfigOptionCategory::Other("some_future_category".to_string())
7721        );
7722
7723        // Test round-trip of unknown category
7724        let json = serde_json::to_value(&unknown).unwrap();
7725        assert_eq!(json, json!("some_future_category"));
7726    }
7727
7728    #[cfg(not(feature = "unstable_speed_config_category"))]
7729    #[test]
7730    fn test_session_config_option_speed_is_unknown_without_feature() {
7731        let unknown: SessionConfigOptionCategory = serde_json::from_str("\"speed\"").unwrap();
7732        assert_eq!(
7733            unknown,
7734            SessionConfigOptionCategory::Other("speed".to_string())
7735        );
7736    }
7737
7738    #[test]
7739    fn test_session_config_option_category_custom_categories() {
7740        // Category names beginning with `_` are free for custom use
7741        let custom: SessionConfigOptionCategory =
7742            serde_json::from_str("\"_my_custom_category\"").unwrap();
7743        assert_eq!(
7744            custom,
7745            SessionConfigOptionCategory::Other("_my_custom_category".to_string())
7746        );
7747
7748        // Test round-trip preserves the custom category name
7749        let json = serde_json::to_value(&custom).unwrap();
7750        assert_eq!(json, json!("_my_custom_category"));
7751
7752        // Deserialize back and verify
7753        let deserialized: SessionConfigOptionCategory = serde_json::from_value(json).unwrap();
7754        assert_eq!(
7755            deserialized,
7756            SessionConfigOptionCategory::Other("_my_custom_category".to_string()),
7757        );
7758    }
7759
7760    #[test]
7761    fn test_auth_method_agent_serialization() {
7762        let method = AuthMethod::Agent(AuthMethodAgent::new("default-auth", "Default Auth"));
7763
7764        let json = serde_json::to_value(&method).unwrap();
7765        assert_eq!(
7766            json,
7767            json!({
7768                "id": "default-auth",
7769                "name": "Default Auth"
7770            })
7771        );
7772        // description should be omitted when None
7773        assert!(!json.as_object().unwrap().contains_key("description"));
7774        // Agent variant should not emit a `type` field (backward compat)
7775        assert!(!json.as_object().unwrap().contains_key("type"));
7776
7777        let deserialized: AuthMethod = serde_json::from_value(json).unwrap();
7778        match deserialized {
7779            AuthMethod::Agent(AuthMethodAgent { id, name, .. }) => {
7780                assert_eq!(id.0.as_ref(), "default-auth");
7781                assert_eq!(name, "Default Auth");
7782            }
7783            _ => panic!("Expected Agent variant"),
7784        }
7785    }
7786
7787    #[test]
7788    fn test_auth_method_explicit_agent_deserialization() {
7789        // An explicit `"type": "agent"` should also deserialize to Agent
7790        let json = json!({
7791            "id": "agent-auth",
7792            "name": "Agent Auth",
7793            "type": "agent"
7794        });
7795
7796        let deserialized: AuthMethod = serde_json::from_value(json).unwrap();
7797        assert!(matches!(deserialized, AuthMethod::Agent(_)));
7798    }
7799
7800    #[test]
7801    fn test_session_delete_serialization() {
7802        assert_eq!(AGENT_METHOD_NAMES.session_delete, "session/delete");
7803        assert_eq!(
7804            ClientRequest::DeleteSessionRequest(DeleteSessionRequest::new("sess_abc123")).method(),
7805            "session/delete"
7806        );
7807        assert_eq!(
7808            serde_json::to_value(DeleteSessionRequest::new("sess_abc123")).unwrap(),
7809            json!({
7810                "sessionId": "sess_abc123"
7811            })
7812        );
7813        assert_eq!(
7814            serde_json::to_value(DeleteSessionResponse::new()).unwrap(),
7815            json!({})
7816        );
7817        assert_eq!(
7818            serde_json::to_value(
7819                SessionCapabilities::new().delete(SessionDeleteCapabilities::new())
7820            )
7821            .unwrap(),
7822            json!({
7823                "delete": {}
7824            })
7825        );
7826    }
7827    #[cfg(feature = "unstable_session_set_title")]
7828    #[test]
7829    fn test_session_set_title_serialization() {
7830        assert_eq!(AGENT_METHOD_NAMES.session_set_title, "session/set_title");
7831        assert_eq!(
7832            ClientRequest::SetSessionTitleRequest(SetSessionTitleRequest::new(
7833                "sess_abc123",
7834                "Investigate OAuth timeout"
7835            ))
7836            .method(),
7837            "session/set_title"
7838        );
7839        assert_eq!(
7840            serde_json::to_value(SetSessionTitleRequest::new(
7841                "sess_abc123",
7842                "Investigate OAuth timeout"
7843            ))
7844            .unwrap(),
7845            json!({
7846                "sessionId": "sess_abc123",
7847                "title": "Investigate OAuth timeout"
7848            })
7849        );
7850        assert_eq!(
7851            serde_json::to_value(SetSessionTitleResponse::new("Investigate OAuth timeout"))
7852                .unwrap(),
7853            json!({
7854                "title": "Investigate OAuth timeout"
7855            })
7856        );
7857        assert_eq!(
7858            serde_json::to_value(SessionCapabilities::new().title(SessionTitleCapabilities::new()))
7859                .unwrap(),
7860            json!({
7861                "title": {}
7862            })
7863        );
7864    }
7865
7866    #[cfg(feature = "unstable_session_set_title")]
7867    #[test]
7868    fn test_session_set_title_requires_title() {
7869        for params in [
7870            json!({"sessionId": "sess_abc123"}),
7871            json!({"sessionId": "sess_abc123", "title": null}),
7872            json!({"sessionId": "sess_abc123", "title": 42}),
7873        ] {
7874            assert!(serde_json::from_value::<SetSessionTitleRequest>(params).is_err());
7875        }
7876        for result in [json!({}), json!({"title": null})] {
7877            assert!(serde_json::from_value::<SetSessionTitleResponse>(result).is_err());
7878        }
7879    }
7880
7881    #[cfg(feature = "unstable_session_options")]
7882    #[test]
7883    fn test_session_options_serialization() {
7884        assert_eq!(AGENT_METHOD_NAMES.session_options, "session/options");
7885        assert_eq!(
7886            ClientRequest::SessionOptionsRequest(SessionOptionsRequest::new("/home/user/project"))
7887                .method(),
7888            "session/options"
7889        );
7890        assert_eq!(
7891            serde_json::to_value(
7892                SessionOptionsRequest::new("/home/user/project")
7893                    .session_id(SessionId::new("sess_abc123"))
7894            )
7895            .unwrap(),
7896            json!({"cwd": "/home/user/project", "sessionId": "sess_abc123"})
7897        );
7898        assert_eq!(
7899            serde_json::from_value::<SessionOptionsRequest>(
7900                json!({"cwd": "/home/user/project", "additionalDirectories": null, "sessionId": null})
7901            )
7902            .unwrap(),
7903            SessionOptionsRequest::new("/home/user/project")
7904        );
7905        let request = NewSessionRequest::new("/home/user/project").config_options(vec![
7906            InitialSessionConfigOption::new("model", SessionConfigOptionValue::value_id("model-2")),
7907            InitialSessionConfigOption::new("fast", SessionConfigOptionValue::boolean(true)),
7908        ]);
7909        let value = serde_json::to_value(&request).unwrap();
7910        assert_eq!(
7911            value["configOptions"],
7912            json!([
7913                {"configId": "model", "value": "model-2"},
7914                {"configId": "fast", "type": "boolean", "value": true}
7915            ])
7916        );
7917        assert_eq!(
7918            serde_json::from_value::<NewSessionRequest>(value).unwrap(),
7919            request
7920        );
7921        assert!(
7922            serde_json::from_value::<NewSessionRequest>(json!({
7923                "cwd": "/home/user/project",
7924                "mcpServers": [],
7925                "configOptions": [{"type": "boolean", "value": true}]
7926            }))
7927            .is_err()
7928        );
7929        assert_eq!(
7930            serde_json::to_value(SessionOptionsResponse::new()).unwrap(),
7931            json!({})
7932        );
7933        #[cfg(feature = "unstable_session_fork")]
7934        {
7935            let fork =
7936                ForkSessionRequest::new("sess_abc123", "/home/user/project").config_options(vec![
7937                    InitialSessionConfigOption::new(
7938                        "model",
7939                        SessionConfigOptionValue::value_id("model-2"),
7940                    ),
7941                ]);
7942            let value = serde_json::to_value(&fork).unwrap();
7943            assert_eq!(
7944                value["configOptions"],
7945                json!([{"configId": "model", "value": "model-2"}])
7946            );
7947            assert_eq!(
7948                serde_json::from_value::<ForkSessionRequest>(value).unwrap(),
7949                fork
7950            );
7951            // `null` is an empty list, and a malformed entry fails the request.
7952            assert_eq!(
7953                serde_json::from_value::<ForkSessionRequest>(json!({
7954                    "sessionId": "sess_abc123",
7955                    "cwd": "/home/user/project",
7956                    "configOptions": null
7957                }))
7958                .unwrap(),
7959                ForkSessionRequest::new("sess_abc123", "/home/user/project")
7960            );
7961            assert!(
7962                serde_json::from_value::<ForkSessionRequest>(json!({
7963                    "sessionId": "sess_abc123",
7964                    "cwd": "/home/user/project",
7965                    "configOptions": [{"type": "boolean", "value": true}]
7966                }))
7967                .is_err()
7968            );
7969        }
7970        assert_eq!(
7971            serde_json::to_value(
7972                SessionCapabilities::new().options(SessionOptionsCapabilities::new())
7973            )
7974            .unwrap(),
7975            json!({"options": {}})
7976        );
7977    }
7978
7979    #[cfg(feature = "unstable_session_status")]
7980    #[test]
7981    fn test_session_status_serialization() {
7982        assert_eq!(AGENT_METHOD_NAMES.session_status, "session/status");
7983        assert_eq!(
7984            ClientRequest::SessionStatusRequest(SessionStatusRequest::new("sess_abc123")).method(),
7985            "session/status"
7986        );
7987        assert_eq!(
7988            serde_json::to_value(SessionStatusRequest::new("sess_abc123")).unwrap(),
7989            json!({"sessionId": "sess_abc123"})
7990        );
7991        assert_eq!(
7992            serde_json::to_value(SessionStatusResponse::new(SessionStatus::Saved)).unwrap(),
7993            json!({"status": "saved"})
7994        );
7995        assert_eq!(
7996            serde_json::to_value(
7997                SessionCapabilities::new().status(SessionStatusCapabilities::new())
7998            )
7999            .unwrap(),
8000            json!({"status": {}})
8001        );
8002    }
8003
8004    #[cfg(feature = "unstable_session_status")]
8005    #[test]
8006    fn test_session_status_is_strict_and_open() {
8007        let custom =
8008            serde_json::from_value::<SessionStatusResponse>(json!({"status": "_suspended"}))
8009                .unwrap();
8010        assert_eq!(
8011            custom.status,
8012            SessionStatus::Other("_suspended".to_string())
8013        );
8014        assert_eq!(
8015            serde_json::to_value(&custom).unwrap(),
8016            json!({"status": "_suspended"})
8017        );
8018        for result in [json!({}), json!({"status": null}), json!({"status": 1})] {
8019            assert!(serde_json::from_value::<SessionStatusResponse>(result).is_err());
8020        }
8021        for params in [json!({}), json!({"sessionId": null})] {
8022            assert!(serde_json::from_value::<SessionStatusRequest>(params).is_err());
8023        }
8024    }
8025
8026    #[cfg(feature = "unstable_session_archive")]
8027    #[test]
8028    fn test_session_archive_serialization() {
8029        assert_eq!(AGENT_METHOD_NAMES.session_archive, "session/archive");
8030        assert_eq!(AGENT_METHOD_NAMES.session_unarchive, "session/unarchive");
8031        assert_eq!(
8032            ClientRequest::ArchiveSessionRequest(ArchiveSessionRequest::new("sess_abc123"))
8033                .method(),
8034            "session/archive"
8035        );
8036        assert_eq!(
8037            ClientRequest::UnarchiveSessionRequest(UnarchiveSessionRequest::new("sess_abc123"))
8038                .method(),
8039            "session/unarchive"
8040        );
8041        assert_eq!(
8042            serde_json::to_value(ArchiveSessionRequest::new("sess_abc123")).unwrap(),
8043            json!({"sessionId": "sess_abc123"})
8044        );
8045        assert_eq!(
8046            serde_json::to_value(UnarchiveSessionResponse::new()).unwrap(),
8047            json!({})
8048        );
8049        assert_eq!(
8050            serde_json::to_value(
8051                SessionCapabilities::new().archive(SessionArchiveCapabilities::new())
8052            )
8053            .unwrap(),
8054            json!({"archive": {}})
8055        );
8056        assert_eq!(
8057            serde_json::to_value(
8058                ListSessionsRequest::new()
8059                    .cwd("/home/user/project")
8060                    .archived(SessionArchiveFilter::Only)
8061            )
8062            .unwrap(),
8063            json!({"cwd": "/home/user/project", "archived": "only"})
8064        );
8065        assert_eq!(
8066            serde_json::to_value(
8067                SessionInfo::new("sess_abc123", "/home/user/project").archived(true)
8068            )
8069            .unwrap(),
8070            json!({"sessionId": "sess_abc123", "cwd": "/home/user/project", "archived": true})
8071        );
8072    }
8073
8074    #[cfg(feature = "unstable_session_archive")]
8075    #[test]
8076    fn test_session_archive_filter_is_strict_and_open() {
8077        for (value, expected) in [
8078            (json!(null), None),
8079            (json!("include"), Some(SessionArchiveFilter::Include)),
8080            (
8081                json!("_recent"),
8082                Some(SessionArchiveFilter::Other("_recent".to_string())),
8083            ),
8084        ] {
8085            let request =
8086                serde_json::from_value::<ListSessionsRequest>(json!({"archived": value})).unwrap();
8087            assert_eq!(request.archived, expected);
8088        }
8089        for value in [json!(true), json!(1), json!({})] {
8090            assert!(
8091                serde_json::from_value::<ListSessionsRequest>(json!({"archived": value})).is_err()
8092            );
8093        }
8094        let info = serde_json::from_value::<SessionInfo>(
8095            json!({"sessionId": "sess_abc123", "cwd": "/home/user/project", "archived": "yes"}),
8096        )
8097        .unwrap();
8098        assert_eq!(info.archived, None);
8099    }
8100
8101    #[test]
8102    fn test_session_additional_directories_serialization() {
8103        assert_eq!(
8104            serde_json::to_value(NewSessionRequest::new("/home/user/project")).unwrap(),
8105            json!({
8106                "cwd": "/home/user/project",
8107                "mcpServers": []
8108            })
8109        );
8110        assert_eq!(
8111            serde_json::to_value(
8112                NewSessionRequest::new("/home/user/project").additional_directories(vec![
8113                    PathBuf::from("/home/user/shared-lib"),
8114                    PathBuf::from("/home/user/product-docs"),
8115                ])
8116            )
8117            .unwrap(),
8118            json!({
8119                "cwd": "/home/user/project",
8120                "additionalDirectories": [
8121                    "/home/user/shared-lib",
8122                    "/home/user/product-docs"
8123                ],
8124                "mcpServers": []
8125            })
8126        );
8127        assert_eq!(
8128            serde_json::to_value(SessionInfo::new("sess_abc123", "/home/user/project")).unwrap(),
8129            json!({
8130                "sessionId": "sess_abc123",
8131                "cwd": "/home/user/project"
8132            })
8133        );
8134        assert_eq!(
8135            serde_json::to_value(
8136                SessionInfo::new("sess_abc123", "/home/user/project").additional_directories(vec![
8137                    PathBuf::from("/home/user/shared-lib"),
8138                    PathBuf::from("/home/user/product-docs"),
8139                ])
8140            )
8141            .unwrap(),
8142            json!({
8143                "sessionId": "sess_abc123",
8144                "cwd": "/home/user/project",
8145                "additionalDirectories": [
8146                    "/home/user/shared-lib",
8147                    "/home/user/product-docs"
8148                ]
8149            })
8150        );
8151        assert_eq!(
8152            serde_json::from_value::<SessionInfo>(json!({
8153                "sessionId": "sess_abc123",
8154                "cwd": "/home/user/project"
8155            }))
8156            .unwrap()
8157            .additional_directories,
8158            Vec::<PathBuf>::new()
8159        );
8160    }
8161    #[test]
8162    fn test_session_additional_directories_capabilities_serialization() {
8163        assert_eq!(
8164            serde_json::to_value(
8165                SessionCapabilities::new()
8166                    .additional_directories(SessionAdditionalDirectoriesCapabilities::new())
8167            )
8168            .unwrap(),
8169            json!({
8170                "additionalDirectories": {}
8171            })
8172        );
8173    }
8174
8175    #[test]
8176    fn test_session_system_prompt_capabilities_serialization() {
8177        assert_eq!(
8178            serde_json::to_value(
8179                SessionCapabilities::new().system_prompt(SessionSystemPromptCapabilities::new())
8180            )
8181            .unwrap(),
8182            json!({ "systemPrompt": {} })
8183        );
8184        assert_eq!(
8185            serde_json::to_value(
8186                SessionCapabilities::new().system_prompt(
8187                    SessionSystemPromptCapabilities::new().mode(
8188                        SessionSystemPromptModeCapabilities::new()
8189                            .override_(SessionSystemPromptOverrideCapabilities::new())
8190                    )
8191                )
8192            )
8193            .unwrap(),
8194            json!({ "systemPrompt": { "mode": { "override": {} } } })
8195        );
8196        assert_eq!(
8197            serde_json::from_value::<SessionCapabilities>(
8198                json!({ "systemPrompt": { "mode": { "override": {} } } })
8199            )
8200            .unwrap()
8201            .system_prompt
8202            .and_then(|capabilities| capabilities.mode)
8203            .and_then(|mode| mode.override_),
8204            Some(SessionSystemPromptOverrideCapabilities::new())
8205        );
8206
8207        // Capabilities fall back to "not advertised" when malformed.
8208        assert_eq!(
8209            serde_json::from_value::<SessionCapabilities>(json!({ "systemPrompt": "yes" }))
8210                .unwrap()
8211                .system_prompt,
8212            None
8213        );
8214        assert_eq!(
8215            serde_json::from_value::<SessionCapabilities>(
8216                json!({ "systemPrompt": { "mode": { "override": true } } })
8217            )
8218            .unwrap()
8219            .system_prompt,
8220            Some(
8221                SessionSystemPromptCapabilities::new()
8222                    .mode(SessionSystemPromptModeCapabilities::new())
8223            )
8224        );
8225        assert_eq!(
8226            serde_json::from_value::<SessionCapabilities>(
8227                json!({ "systemPrompt": { "mode": "override" } })
8228            )
8229            .unwrap()
8230            .system_prompt,
8231            Some(SessionSystemPromptCapabilities::new())
8232        );
8233    }
8234
8235    #[test]
8236    fn test_system_prompt_lifecycle_request_serialization() {
8237        let system_prompt = SystemPrompt::new(vec![ContentBlock::from(
8238            "You are a code review specialist.",
8239        )]);
8240        let system_prompt_json = json!({
8241            "mode": "append",
8242            "content": [{ "type": "text", "text": "You are a code review specialist." }]
8243        });
8244
8245        let request =
8246            NewSessionRequest::new("/home/user/project").system_prompt(system_prompt.clone());
8247        let request_json = json!({
8248            "cwd": "/home/user/project",
8249            "mcpServers": [],
8250            "systemPrompt": system_prompt_json
8251        });
8252        assert_eq!(serde_json::to_value(&request).unwrap(), request_json);
8253        assert_eq!(
8254            serde_json::from_value::<NewSessionRequest>(request_json).unwrap(),
8255            request
8256        );
8257
8258        assert_eq!(
8259            serde_json::to_value(
8260                LoadSessionRequest::new("sess_abc123", "/home/user/project")
8261                    .system_prompt(system_prompt.clone())
8262            )
8263            .unwrap()["systemPrompt"],
8264            system_prompt_json
8265        );
8266        assert_eq!(
8267            serde_json::to_value(
8268                ResumeSessionRequest::new("sess_abc123", "/home/user/project")
8269                    .system_prompt(system_prompt.clone())
8270            )
8271            .unwrap()["systemPrompt"],
8272            system_prompt_json
8273        );
8274        #[cfg(feature = "unstable_session_fork")]
8275        assert_eq!(
8276            serde_json::to_value(
8277                ForkSessionRequest::new("sess_abc123", "/home/user/project")
8278                    .system_prompt(system_prompt.clone())
8279            )
8280            .unwrap()["systemPrompt"],
8281            system_prompt_json
8282        );
8283
8284        let override_prompt =
8285            SystemPrompt::new(vec![ContentBlock::from("...")]).mode(SystemPromptMode::Override);
8286        let override_json = json!({
8287            "mode": "override",
8288            "content": [{ "type": "text", "text": "..." }]
8289        });
8290        assert_eq!(
8291            serde_json::to_value(&override_prompt).unwrap(),
8292            override_json
8293        );
8294        assert_eq!(
8295            serde_json::from_value::<SystemPrompt>(override_json).unwrap(),
8296            override_prompt
8297        );
8298    }
8299
8300    /// `SystemPrompt::new` defaults to `append` in Rust, but `mode` is required on
8301    /// the wire, so it is always serialized.
8302    #[test]
8303    fn test_system_prompt_new_defaults_to_append() {
8304        let system_prompt = SystemPrompt::new(vec![ContentBlock::from("...")]);
8305        assert_eq!(system_prompt.mode, SystemPromptMode::Append);
8306        assert_eq!(
8307            serde_json::to_value(&system_prompt).unwrap(),
8308            json!({ "mode": "append", "content": [{ "type": "text", "text": "..." }] })
8309        );
8310    }
8311
8312    /// Unknown modes follow the enum variant extension rule: they parse as
8313    /// `SystemPromptMode::Other` so they are not dropped, and an agent that does
8314    /// not support them must reject the request.
8315    #[test]
8316    fn test_system_prompt_preserves_unknown_modes() {
8317        for mode in ["_vendor_mode", "prepend"] {
8318            let system_prompt_json =
8319                json!({ "mode": mode, "content": [{ "type": "text", "text": "..." }] });
8320            let system_prompt: SystemPrompt =
8321                serde_json::from_value(system_prompt_json.clone()).unwrap();
8322            assert_eq!(
8323                system_prompt.mode,
8324                SystemPromptMode::Other(mode.to_string())
8325            );
8326            assert_eq!(
8327                serde_json::to_value(&system_prompt).unwrap(),
8328                system_prompt_json
8329            );
8330        }
8331    }
8332
8333    /// The receiver acts on `systemPrompt`, so malformed values fail the request
8334    /// (`-32602`) instead of creating a session without the prompt, and `null`
8335    /// is equivalent to omitting the field.
8336    fn assert_system_prompt_is_strict<T>(base: &serde_json::Value)
8337    where
8338        T: serde::de::DeserializeOwned + PartialEq + std::fmt::Debug,
8339    {
8340        let name = std::any::type_name::<T>();
8341        let with = |system_prompt: serde_json::Value| {
8342            let mut request = base.clone();
8343            request["systemPrompt"] = system_prompt;
8344            serde_json::from_value::<T>(request)
8345        };
8346
8347        for system_prompt in [
8348            json!("You are a code review specialist."),
8349            json!({ "content": [{ "type": "text", "text": "..." }] }),
8350            json!({ "mode": null, "content": [{ "type": "text", "text": "..." }] }),
8351            json!({ "mode": 1, "content": [{ "type": "text", "text": "..." }] }),
8352            json!({ "mode": "append" }),
8353            json!({ "mode": "append", "content": "..." }),
8354            json!({ "mode": "append", "content": [{ "type": "text" }] }),
8355            json!({ "mode": "append", "content": [{ "type": "video", "uri": "..." }] }),
8356        ] {
8357            assert!(
8358                with(system_prompt.clone()).is_err(),
8359                "{name}.systemPrompt: {system_prompt}"
8360            );
8361        }
8362
8363        assert_eq!(
8364            with(serde_json::Value::Null).unwrap(),
8365            serde_json::from_value::<T>(base.clone()).unwrap(),
8366            "{name}.systemPrompt"
8367        );
8368    }
8369
8370    #[test]
8371    fn test_session_setup_requests_reject_malformed_system_prompts() {
8372        assert!(
8373            serde_json::to_value(NewSessionRequest::new("/repo"))
8374                .unwrap()
8375                .get("systemPrompt")
8376                .is_none()
8377        );
8378        assert_system_prompt_is_strict::<NewSessionRequest>(&json!({
8379            "cwd": "/repo",
8380            "mcpServers": []
8381        }));
8382        assert_system_prompt_is_strict::<LoadSessionRequest>(&json!({
8383            "sessionId": "sess-1",
8384            "cwd": "/repo",
8385            "mcpServers": []
8386        }));
8387        assert_system_prompt_is_strict::<ResumeSessionRequest>(&json!({
8388            "sessionId": "sess-1",
8389            "cwd": "/repo"
8390        }));
8391        #[cfg(feature = "unstable_session_fork")]
8392        assert_system_prompt_is_strict::<ForkSessionRequest>(&json!({
8393            "sessionId": "sess-1",
8394            "cwd": "/repo"
8395        }));
8396    }
8397
8398    #[test]
8399    fn test_auth_method_terminal_serialization() {
8400        let method = AuthMethod::Terminal(AuthMethodTerminal::new("tui-auth", "Terminal Auth"));
8401
8402        let json = serde_json::to_value(&method).unwrap();
8403        assert_eq!(
8404            json,
8405            json!({
8406                "id": "tui-auth",
8407                "name": "Terminal Auth",
8408                "type": "terminal"
8409            })
8410        );
8411        // args and env should be omitted when empty
8412        assert!(!json.as_object().unwrap().contains_key("args"));
8413        assert!(!json.as_object().unwrap().contains_key("env"));
8414
8415        let deserialized: AuthMethod = serde_json::from_value(json).unwrap();
8416        match deserialized {
8417            AuthMethod::Terminal(AuthMethodTerminal { args, env, .. }) => {
8418                assert_eq!(args, Vec::<String>::new());
8419                assert!(env.is_empty());
8420            }
8421            _ => panic!("Expected Terminal variant"),
8422        }
8423    }
8424
8425    #[test]
8426    fn test_auth_method_terminal_with_args_and_env_serialization() {
8427        use std::collections::HashMap;
8428
8429        let mut env = HashMap::new();
8430        env.insert("TERM".to_string(), "xterm-256color".to_string());
8431
8432        let method = AuthMethod::Terminal(
8433            AuthMethodTerminal::new("tui-auth", "Terminal Auth")
8434                .args(vec!["--interactive".to_string(), "--color".to_string()])
8435                .env(env),
8436        );
8437
8438        let json = serde_json::to_value(&method).unwrap();
8439        assert_eq!(
8440            json,
8441            json!({
8442                "id": "tui-auth",
8443                "name": "Terminal Auth",
8444                "type": "terminal",
8445                "args": ["--interactive", "--color"],
8446                "env": {
8447                    "TERM": "xterm-256color"
8448                }
8449            })
8450        );
8451
8452        let deserialized: AuthMethod = serde_json::from_value(json).unwrap();
8453        match deserialized {
8454            AuthMethod::Terminal(AuthMethodTerminal { args, env, .. }) => {
8455                assert_eq!(args, vec!["--interactive", "--color"]);
8456                assert_eq!(env.len(), 1);
8457                assert_eq!(env.get("TERM").unwrap(), "xterm-256color");
8458            }
8459            _ => panic!("Expected Terminal variant"),
8460        }
8461    }
8462
8463    #[test]
8464    fn test_session_config_option_value_id_serialize() {
8465        let val = SessionConfigOptionValue::value_id("model-1");
8466        let json = serde_json::to_value(&val).unwrap();
8467        // ValueId omits the "type" field (it's the default)
8468        assert_eq!(json, json!({ "value": "model-1" }));
8469        assert!(!json.as_object().unwrap().contains_key("type"));
8470    }
8471
8472    #[test]
8473    fn test_session_config_option_value_boolean_serialize() {
8474        let val = SessionConfigOptionValue::boolean(true);
8475        let json = serde_json::to_value(&val).unwrap();
8476        assert_eq!(json, json!({ "type": "boolean", "value": true }));
8477    }
8478
8479    #[test]
8480    fn test_session_config_option_value_deserialize_no_type() {
8481        // Missing "type" should default to ValueId
8482        let json = json!({ "value": "model-1" });
8483        let val: SessionConfigOptionValue = serde_json::from_value(json).unwrap();
8484        assert_eq!(val, SessionConfigOptionValue::value_id("model-1"));
8485        assert_eq!(val.as_value_id().unwrap().to_string(), "model-1");
8486    }
8487
8488    #[test]
8489    fn test_session_config_option_value_deserialize_boolean() {
8490        let json = json!({ "type": "boolean", "value": true });
8491        let val: SessionConfigOptionValue = serde_json::from_value(json).unwrap();
8492        assert_eq!(val, SessionConfigOptionValue::boolean(true));
8493        assert_eq!(val.as_bool(), Some(true));
8494    }
8495
8496    #[test]
8497    fn test_session_config_option_value_deserialize_boolean_false() {
8498        let json = json!({ "type": "boolean", "value": false });
8499        let val: SessionConfigOptionValue = serde_json::from_value(json).unwrap();
8500        assert_eq!(val, SessionConfigOptionValue::boolean(false));
8501        assert_eq!(val.as_bool(), Some(false));
8502    }
8503
8504    #[test]
8505    fn test_session_config_option_value_deserialize_unknown_type_with_string_value() {
8506        // Unknown type with a string value gracefully falls back to ValueId
8507        let json = json!({ "type": "text", "value": "freeform input" });
8508        let val: SessionConfigOptionValue = serde_json::from_value(json).unwrap();
8509        assert_eq!(val.as_value_id().unwrap().to_string(), "freeform input");
8510    }
8511
8512    #[test]
8513    fn test_session_config_option_value_roundtrip_value_id() {
8514        let original = SessionConfigOptionValue::value_id("option-a");
8515        let json = serde_json::to_value(&original).unwrap();
8516        let roundtripped: SessionConfigOptionValue = serde_json::from_value(json).unwrap();
8517        assert_eq!(original, roundtripped);
8518    }
8519
8520    #[test]
8521    fn test_session_config_option_value_roundtrip_boolean() {
8522        let original = SessionConfigOptionValue::boolean(false);
8523        let json = serde_json::to_value(&original).unwrap();
8524        let roundtripped: SessionConfigOptionValue = serde_json::from_value(json).unwrap();
8525        assert_eq!(original, roundtripped);
8526    }
8527
8528    #[test]
8529    fn test_session_config_option_value_type_mismatch_boolean_with_string() {
8530        // type says "boolean" but value is a string — falls to untagged ValueId
8531        let json = json!({ "type": "boolean", "value": "not a bool" });
8532        let result = serde_json::from_value::<SessionConfigOptionValue>(json);
8533        // serde tries Boolean first (fails), then falls to untagged ValueId (succeeds)
8534        assert!(result.is_ok());
8535        assert_eq!(
8536            result.unwrap().as_value_id().unwrap().to_string(),
8537            "not a bool"
8538        );
8539    }
8540
8541    #[test]
8542    fn test_session_config_option_value_from_impls() {
8543        let from_str: SessionConfigOptionValue = "model-1".into();
8544        assert_eq!(from_str.as_value_id().unwrap().to_string(), "model-1");
8545
8546        let from_id: SessionConfigOptionValue = SessionConfigValueId::new("model-2").into();
8547        assert_eq!(from_id.as_value_id().unwrap().to_string(), "model-2");
8548
8549        let from_bool: SessionConfigOptionValue = true.into();
8550        assert_eq!(from_bool.as_bool(), Some(true));
8551    }
8552
8553    #[test]
8554    fn test_set_session_config_option_request_value_id() {
8555        let req = SetSessionConfigOptionRequest::new("sess_1", "model", "model-1");
8556        let json = serde_json::to_value(&req).unwrap();
8557        assert_eq!(
8558            json,
8559            json!({
8560                "sessionId": "sess_1",
8561                "configId": "model",
8562                "value": "model-1"
8563            })
8564        );
8565        // No "type" field for value_id
8566        assert!(!json.as_object().unwrap().contains_key("type"));
8567    }
8568
8569    #[test]
8570    fn test_set_session_config_option_request_boolean() {
8571        let req = SetSessionConfigOptionRequest::new("sess_1", "brave_mode", true);
8572        let json = serde_json::to_value(&req).unwrap();
8573        assert_eq!(
8574            json,
8575            json!({
8576                "sessionId": "sess_1",
8577                "configId": "brave_mode",
8578                "type": "boolean",
8579                "value": true
8580            })
8581        );
8582    }
8583
8584    #[test]
8585    fn test_set_session_config_option_request_deserialize_no_type() {
8586        // Backwards-compatible: no "type" field → value_id
8587        let json = json!({
8588            "sessionId": "sess_1",
8589            "configId": "model",
8590            "value": "model-1"
8591        });
8592        let req: SetSessionConfigOptionRequest = serde_json::from_value(json).unwrap();
8593        assert_eq!(req.session_id.to_string(), "sess_1");
8594        assert_eq!(req.config_id.to_string(), "model");
8595        assert_eq!(req.value.as_value_id().unwrap().to_string(), "model-1");
8596    }
8597
8598    #[test]
8599    fn test_set_session_config_option_request_deserialize_boolean() {
8600        let json = json!({
8601            "sessionId": "sess_1",
8602            "configId": "brave_mode",
8603            "type": "boolean",
8604            "value": true
8605        });
8606        let req: SetSessionConfigOptionRequest = serde_json::from_value(json).unwrap();
8607        assert_eq!(req.value.as_bool(), Some(true));
8608    }
8609
8610    #[test]
8611    fn test_set_session_config_option_request_roundtrip_value_id() {
8612        let original = SetSessionConfigOptionRequest::new("s", "c", "v");
8613        let json = serde_json::to_value(&original).unwrap();
8614        let roundtripped: SetSessionConfigOptionRequest = serde_json::from_value(json).unwrap();
8615        assert_eq!(original, roundtripped);
8616    }
8617
8618    #[test]
8619    fn test_set_session_config_option_request_roundtrip_boolean() {
8620        let original = SetSessionConfigOptionRequest::new("s", "c", false);
8621        let json = serde_json::to_value(&original).unwrap();
8622        let roundtripped: SetSessionConfigOptionRequest = serde_json::from_value(json).unwrap();
8623        assert_eq!(original, roundtripped);
8624    }
8625
8626    #[test]
8627    fn test_session_config_boolean_serialization() {
8628        let cfg = SessionConfigBoolean::new(true);
8629        let json = serde_json::to_value(&cfg).unwrap();
8630        assert_eq!(json, json!({ "currentValue": true }));
8631
8632        let deserialized: SessionConfigBoolean = serde_json::from_value(json).unwrap();
8633        assert!(deserialized.current_value);
8634    }
8635
8636    #[test]
8637    fn test_session_config_option_boolean_variant() {
8638        let opt = SessionConfigOption::boolean("brave_mode", "Brave Mode", false)
8639            .description("Skip confirmation prompts")
8640            .meta(test_meta());
8641        assert_eq!(serialized_meta_key_count(&opt), 1);
8642
8643        let json = serde_json::to_value(&opt).unwrap();
8644        assert_eq!(
8645            json,
8646            json!({
8647                "id": "brave_mode",
8648                "name": "Brave Mode",
8649                "description": "Skip confirmation prompts",
8650                "type": "boolean",
8651                "currentValue": false,
8652                "_meta": {
8653                    "source": "test"
8654                }
8655            })
8656        );
8657
8658        let deserialized: SessionConfigOption = serde_json::from_value(json).unwrap();
8659        assert_eq!(deserialized.id.to_string(), "brave_mode");
8660        assert_eq!(deserialized.name, "Brave Mode");
8661        match deserialized.kind {
8662            SessionConfigKind::Boolean(ref b) => assert!(!b.current_value),
8663            _ => panic!("Expected Boolean kind"),
8664        }
8665    }
8666
8667    #[test]
8668    fn test_session_config_option_select_still_works() {
8669        // Make sure existing select options are unaffected
8670        let opt = SessionConfigOption::select(
8671            "model",
8672            "Model",
8673            "model-1",
8674            vec![
8675                SessionConfigSelectOption::new("model-1", "Model 1"),
8676                SessionConfigSelectOption::new("model-2", "Model 2"),
8677            ],
8678        )
8679        .meta(test_meta());
8680        assert_eq!(serialized_meta_key_count(&opt), 1);
8681
8682        let json = serde_json::to_value(&opt).unwrap();
8683        assert_eq!(json["type"], "select");
8684        assert_eq!(json["currentValue"], "model-1");
8685        assert_eq!(json["options"].as_array().unwrap().len(), 2);
8686        assert_eq!(json["_meta"]["source"], "test");
8687
8688        let deserialized: SessionConfigOption = serde_json::from_value(json).unwrap();
8689        match deserialized.kind {
8690            SessionConfigKind::Select(ref s) => {
8691                assert_eq!(s.current_value.to_string(), "model-1");
8692            }
8693            _ => panic!("Expected Select kind"),
8694        }
8695    }
8696
8697    #[cfg(feature = "unstable_llm_providers")]
8698    #[test]
8699    fn test_llm_protocol_known_variants() {
8700        assert_eq!(
8701            serde_json::to_value(&LlmProtocol::Anthropic).unwrap(),
8702            json!("anthropic")
8703        );
8704        assert_eq!(
8705            serde_json::to_value(&LlmProtocol::OpenAi).unwrap(),
8706            json!("openai")
8707        );
8708        assert_eq!(
8709            serde_json::to_value(&LlmProtocol::Azure).unwrap(),
8710            json!("azure")
8711        );
8712        assert_eq!(
8713            serde_json::to_value(&LlmProtocol::Vertex).unwrap(),
8714            json!("vertex")
8715        );
8716        assert_eq!(
8717            serde_json::to_value(&LlmProtocol::Bedrock).unwrap(),
8718            json!("bedrock")
8719        );
8720
8721        assert_eq!(
8722            serde_json::from_str::<LlmProtocol>("\"anthropic\"").unwrap(),
8723            LlmProtocol::Anthropic
8724        );
8725        assert_eq!(
8726            serde_json::from_str::<LlmProtocol>("\"openai\"").unwrap(),
8727            LlmProtocol::OpenAi
8728        );
8729        assert_eq!(
8730            serde_json::from_str::<LlmProtocol>("\"azure\"").unwrap(),
8731            LlmProtocol::Azure
8732        );
8733        assert_eq!(
8734            serde_json::from_str::<LlmProtocol>("\"vertex\"").unwrap(),
8735            LlmProtocol::Vertex
8736        );
8737        assert_eq!(
8738            serde_json::from_str::<LlmProtocol>("\"bedrock\"").unwrap(),
8739            LlmProtocol::Bedrock
8740        );
8741    }
8742
8743    #[cfg(feature = "unstable_llm_providers")]
8744    #[test]
8745    fn test_llm_protocol_unknown_variant() {
8746        let unknown: LlmProtocol = serde_json::from_str("\"cohere\"").unwrap();
8747        assert_eq!(unknown, LlmProtocol::Other("cohere".to_string()));
8748
8749        let json = serde_json::to_value(&unknown).unwrap();
8750        assert_eq!(json, json!("cohere"));
8751    }
8752
8753    #[cfg(feature = "unstable_llm_providers")]
8754    #[test]
8755    fn test_provider_current_config_serialization() {
8756        let config =
8757            ProviderCurrentConfig::new(LlmProtocol::Anthropic, "https://api.anthropic.com");
8758
8759        let json = serde_json::to_value(&config).unwrap();
8760        assert_eq!(
8761            json,
8762            json!({
8763                "apiType": "anthropic",
8764                "baseUrl": "https://api.anthropic.com"
8765            })
8766        );
8767
8768        let deserialized: ProviderCurrentConfig = serde_json::from_value(json).unwrap();
8769        assert_eq!(deserialized.api_type, LlmProtocol::Anthropic);
8770        assert_eq!(deserialized.base_url, "https://api.anthropic.com");
8771    }
8772
8773    #[cfg(feature = "unstable_llm_providers")]
8774    #[test]
8775    fn test_provider_info_with_current_config() {
8776        let info = ProviderInfo::new(
8777            "main",
8778            vec![LlmProtocol::Anthropic, LlmProtocol::OpenAi],
8779            true,
8780            Some(ProviderCurrentConfig::new(
8781                LlmProtocol::Anthropic,
8782                "https://api.anthropic.com",
8783            )),
8784        );
8785
8786        let json = serde_json::to_value(&info).unwrap();
8787        assert_eq!(
8788            json,
8789            json!({
8790                "providerId": "main",
8791                "supported": ["anthropic", "openai"],
8792                "required": true,
8793                "current": {
8794                    "apiType": "anthropic",
8795                    "baseUrl": "https://api.anthropic.com"
8796                }
8797            })
8798        );
8799
8800        let deserialized: ProviderInfo = serde_json::from_value(json).unwrap();
8801        assert_eq!(deserialized.provider_id.to_string(), "main");
8802        assert_eq!(deserialized.supported.len(), 2);
8803        assert!(deserialized.required);
8804        assert!(deserialized.current.is_some());
8805        assert_eq!(
8806            deserialized.current.as_ref().unwrap().api_type,
8807            LlmProtocol::Anthropic
8808        );
8809    }
8810
8811    #[cfg(feature = "unstable_llm_providers")]
8812    #[test]
8813    fn test_provider_info_disabled() {
8814        let info = ProviderInfo::new(
8815            "secondary",
8816            vec![LlmProtocol::OpenAi],
8817            false,
8818            None::<ProviderCurrentConfig>,
8819        );
8820
8821        let json = serde_json::to_value(&info).unwrap();
8822        assert_eq!(
8823            json,
8824            json!({
8825                "providerId": "secondary",
8826                "supported": ["openai"],
8827                "required": false
8828            })
8829        );
8830
8831        let deserialized: ProviderInfo = serde_json::from_value(json).unwrap();
8832        assert_eq!(deserialized.provider_id.to_string(), "secondary");
8833        assert!(!deserialized.required);
8834        assert!(deserialized.current.is_none());
8835    }
8836
8837    #[cfg(feature = "unstable_llm_providers")]
8838    #[test]
8839    fn test_provider_info_missing_current_defaults_to_none() {
8840        // current is optional; omitting it should decode as None
8841        let json = json!({
8842            "providerId": "main",
8843            "supported": ["anthropic"],
8844            "required": true
8845        });
8846        let deserialized: ProviderInfo = serde_json::from_value(json).unwrap();
8847        assert!(deserialized.current.is_none());
8848    }
8849
8850    #[cfg(feature = "unstable_llm_providers")]
8851    #[test]
8852    fn test_provider_info_explicit_null_current_decodes_to_none() {
8853        // current: null and an omitted current are equivalent on the wire;
8854        // both must deserialize into None so the disabled state is preserved
8855        // regardless of which form the peer chose to send.
8856        let json = json!({
8857            "providerId": "main",
8858            "supported": ["anthropic"],
8859            "required": true,
8860            "current": null
8861        });
8862        let deserialized: ProviderInfo = serde_json::from_value(json).unwrap();
8863        assert!(deserialized.current.is_none());
8864    }
8865
8866    #[cfg(feature = "unstable_llm_providers")]
8867    #[test]
8868    fn test_list_providers_response_serialization() {
8869        let response = ListProvidersResponse::new(vec![ProviderInfo::new(
8870            "main",
8871            vec![LlmProtocol::Anthropic],
8872            true,
8873            Some(ProviderCurrentConfig::new(
8874                LlmProtocol::Anthropic,
8875                "https://api.anthropic.com",
8876            )),
8877        )]);
8878
8879        let json = serde_json::to_value(&response).unwrap();
8880        assert_eq!(json["providers"].as_array().unwrap().len(), 1);
8881        assert_eq!(json["providers"][0]["providerId"], "main");
8882
8883        let deserialized: ListProvidersResponse = serde_json::from_value(json).unwrap();
8884        assert_eq!(deserialized.providers.len(), 1);
8885    }
8886
8887    #[cfg(feature = "unstable_llm_providers")]
8888    #[test]
8889    fn test_set_provider_request_serialization() {
8890        let mut headers = IndexMap::new();
8891        headers.insert("Authorization".to_string(), "Bearer sk-test".to_string());
8892
8893        let request =
8894            SetProviderRequest::new("main", LlmProtocol::OpenAi, "https://api.openai.com/v1")
8895                .headers(headers);
8896
8897        let json = serde_json::to_value(&request).unwrap();
8898        assert_eq!(
8899            json,
8900            json!({
8901                "providerId": "main",
8902                "apiType": "openai",
8903                "baseUrl": "https://api.openai.com/v1",
8904                "headers": {
8905                    "Authorization": "Bearer sk-test"
8906                }
8907            })
8908        );
8909
8910        let deserialized: SetProviderRequest = serde_json::from_value(json).unwrap();
8911        assert_eq!(deserialized.provider_id.to_string(), "main");
8912        assert_eq!(deserialized.api_type, LlmProtocol::OpenAi);
8913        assert_eq!(deserialized.base_url, "https://api.openai.com/v1");
8914        assert_eq!(deserialized.headers.len(), 1);
8915        assert_eq!(
8916            deserialized.headers.get("Authorization").unwrap(),
8917            "Bearer sk-test"
8918        );
8919    }
8920
8921    #[cfg(feature = "unstable_llm_providers")]
8922    #[test]
8923    fn test_set_provider_request_omits_empty_headers() {
8924        let request =
8925            SetProviderRequest::new("main", LlmProtocol::Anthropic, "https://api.anthropic.com");
8926
8927        let json = serde_json::to_value(&request).unwrap();
8928        // headers should be omitted when empty
8929        assert!(!json.as_object().unwrap().contains_key("headers"));
8930    }
8931
8932    #[cfg(feature = "unstable_llm_providers")]
8933    #[test]
8934    fn test_disable_provider_request_serialization() {
8935        let request = DisableProviderRequest::new("secondary");
8936
8937        let json = serde_json::to_value(&request).unwrap();
8938        assert_eq!(json, json!({ "providerId": "secondary" }));
8939
8940        let deserialized: DisableProviderRequest = serde_json::from_value(json).unwrap();
8941        assert_eq!(deserialized.provider_id.to_string(), "secondary");
8942    }
8943
8944    #[cfg(feature = "unstable_llm_providers")]
8945    #[test]
8946    fn test_providers_capabilities_serialization() {
8947        let caps = ProvidersCapabilities::new();
8948
8949        let json = serde_json::to_value(&caps).unwrap();
8950        assert_eq!(json, json!({}));
8951
8952        let deserialized: ProvidersCapabilities = serde_json::from_value(json).unwrap();
8953        assert!(deserialized.meta.is_none());
8954    }
8955
8956    #[cfg(feature = "unstable_llm_providers")]
8957    #[test]
8958    fn test_agent_capabilities_with_providers() {
8959        let caps = AgentCapabilities::new().providers(ProvidersCapabilities::new());
8960
8961        let json = serde_json::to_value(&caps).unwrap();
8962        assert_eq!(json["providers"], json!({}));
8963
8964        let deserialized: AgentCapabilities = serde_json::from_value(json).unwrap();
8965        assert!(deserialized.providers.is_some());
8966    }
8967
8968    #[test]
8969    fn prompt_request_rejects_malformed_content_block() {
8970        use serde_json::json;
8971
8972        assert!(
8973            serde_json::from_value::<PromptRequest>(json!({
8974                "sessionId": "sess-1",
8975                "prompt": [{"type": "text"}]
8976            }))
8977            .is_err()
8978        );
8979    }
8980
8981    #[test]
8982    fn prompt_request_rejects_non_array_prompt() {
8983        use serde_json::json;
8984
8985        assert!(
8986            serde_json::from_value::<PromptRequest>(json!({
8987                "sessionId": "sess-1",
8988                "prompt": "hello"
8989            }))
8990            .is_err()
8991        );
8992    }
8993
8994    fn assert_session_setup_lists_are_strict<T>(base: &serde_json::Value)
8995    where
8996        T: serde::de::DeserializeOwned + PartialEq + std::fmt::Debug,
8997    {
8998        let name = std::any::type_name::<T>();
8999        let with = |field: &str, value: serde_json::Value| {
9000            let mut request = base.clone();
9001            request[field] = value;
9002            serde_json::from_value::<T>(request)
9003        };
9004
9005        for (field, value) in [
9006            // Dropping the malformed server would start the session without it.
9007            (
9008                "mcpServers",
9009                json!([
9010                    {"name": "github", "command": "/usr/bin/gh-mcp", "args": [], "env": [{"name": "GITHUB_TOKEN", "value": null}]},
9011                    {"name": "fs", "command": "/usr/bin/fs-mcp", "args": [], "env": []}
9012                ]),
9013            ),
9014            ("mcpServers", json!({"name": "fs"})),
9015            ("additionalDirectories", json!(["/repo/lib", 42])),
9016            ("additionalDirectories", json!("/repo/lib")),
9017        ] {
9018            assert!(
9019                with(field, value.clone()).is_err(),
9020                "{name}.{field}: {value}"
9021            );
9022        }
9023
9024        let empty = serde_json::from_value::<T>(base.clone()).unwrap();
9025        for field in ["mcpServers", "additionalDirectories"] {
9026            assert_eq!(
9027                with(field, serde_json::Value::Null).unwrap(),
9028                empty,
9029                "{name}.{field}"
9030            );
9031        }
9032    }
9033
9034    #[test]
9035    fn session_setup_requests_reject_malformed_mcp_servers_and_directories() {
9036        assert_session_setup_lists_are_strict::<NewSessionRequest>(&json!({
9037            "cwd": "/repo",
9038            "mcpServers": []
9039        }));
9040        assert_session_setup_lists_are_strict::<LoadSessionRequest>(&json!({
9041            "sessionId": "sess-1",
9042            "cwd": "/repo",
9043            "mcpServers": []
9044        }));
9045        assert_session_setup_lists_are_strict::<ResumeSessionRequest>(&json!({
9046            "sessionId": "sess-1",
9047            "cwd": "/repo"
9048        }));
9049        #[cfg(feature = "unstable_session_fork")]
9050        assert_session_setup_lists_are_strict::<ForkSessionRequest>(&json!({
9051            "sessionId": "sess-1",
9052            "cwd": "/repo"
9053        }));
9054    }
9055
9056    #[test]
9057    fn mcp_server_lists_treat_null_as_empty() {
9058        let servers: Vec<McpServer> = serde_json::from_value(json!([
9059            {"name": "fs", "command": "/usr/bin/fs-mcp", "args": null, "env": null},
9060            {"type": "http", "name": "api", "url": "https://example.com/mcp", "headers": null},
9061            {"type": "sse", "name": "events", "url": "https://example.com/sse", "headers": null}
9062        ]))
9063        .unwrap();
9064
9065        assert_eq!(
9066            servers,
9067            vec![
9068                McpServer::Stdio(McpServerStdio::new("fs", "/usr/bin/fs-mcp")),
9069                McpServer::Http(McpServerHttp::new("api", "https://example.com/mcp")),
9070                McpServer::Sse(McpServerSse::new("events", "https://example.com/sse")),
9071            ]
9072        );
9073    }
9074
9075    #[test]
9076    fn terminal_auth_methods_reject_malformed_launch_config() {
9077        // The client spawns a process from `args` and `env`, so a malformed
9078        // method is dropped from `authMethods` instead of launched with
9079        // altered arguments or reinterpreted as an `agent` method.
9080        let response: InitializeResponse = serde_json::from_value(json!({
9081            "protocolVersion": 1,
9082            "authMethods": [
9083                {"type": "terminal", "id": "bad-args", "name": "Log in", "args": ["auth", "--port", 8123]},
9084                {"type": "terminal", "id": "bad-env", "name": "Log in", "env": {"AUTH_MODE": "device", "DEBUG": 1}},
9085                {"type": "terminal", "id": "null-config", "name": "Log in", "args": null, "env": null},
9086                {"id": "agent", "name": "Agent login"}
9087            ]
9088        }))
9089        .unwrap();
9090
9091        assert_eq!(
9092            response.auth_methods,
9093            vec![
9094                AuthMethod::Terminal(AuthMethodTerminal::new("null-config", "Log in")),
9095                AuthMethod::Agent(AuthMethodAgent::new("agent", "Agent login")),
9096            ]
9097        );
9098        assert!(
9099            serde_json::from_value::<AuthMethod>(json!({
9100                "type": "terminal",
9101                "id": "bad-args",
9102                "name": "Log in",
9103                "args": ["auth", 8123]
9104            }))
9105            .is_err()
9106        );
9107    }
9108
9109    #[cfg(feature = "unstable_auth_status")]
9110    #[test]
9111    fn auth_status_response_round_trips() {
9112        let response = AuthStatusResponse::new(AuthState::Authenticated).accounts(vec![
9113            AuthAccount::new("Anthropic API key")
9114                .description("API key helper".to_string())
9115                .active(true),
9116            AuthAccount::new("Claude Max").email("user@example.com".to_string()),
9117        ]);
9118        let json = serde_json::to_value(&response).unwrap();
9119        assert_eq!(
9120            json,
9121            json!({
9122                "state": "authenticated",
9123                "accounts": [
9124                    {
9125                        "label": "Anthropic API key",
9126                        "description": "API key helper",
9127                        "active": true
9128                    },
9129                    {
9130                        "label": "Claude Max",
9131                        "email": "user@example.com"
9132                    }
9133                ]
9134            })
9135        );
9136        assert_eq!(
9137            serde_json::from_value::<AuthStatusResponse>(json).unwrap(),
9138            response
9139        );
9140        assert_eq!(
9141            serde_json::to_value(AuthStatusResponse::new(AuthState::NotRequired)).unwrap(),
9142            json!({"state": "not_required"})
9143        );
9144    }
9145
9146    #[cfg(feature = "unstable_auth_status")]
9147    #[test]
9148    fn auth_status_state_is_strict_and_accounts_are_lenient() {
9149        assert!(serde_json::from_value::<AuthStatusResponse>(json!({})).is_err());
9150        assert!(serde_json::from_value::<AuthStatusResponse>(json!({"state": null})).is_err());
9151        assert!(serde_json::from_value::<AuthStatusResponse>(json!({"state": 1})).is_err());
9152
9153        let response: AuthStatusResponse = serde_json::from_value(json!({
9154            "state": "_vendor_state",
9155            "accounts": [
9156                {"active": true},
9157                {
9158                    "label": "Vertex AI",
9159                    "description": 42,
9160                    "active": "yes",
9161                    "email": ["not", "a", "string"]
9162                }
9163            ]
9164        }))
9165        .unwrap();
9166        assert_eq!(
9167            response,
9168            AuthStatusResponse::new(AuthState::Other("_vendor_state".to_string()))
9169                .accounts(vec![AuthAccount::new("Vertex AI")])
9170        );
9171        assert_eq!(
9172            serde_json::from_value::<AuthStatusResponse>(
9173                json!({"state": "unknown", "accounts": null})
9174            )
9175            .unwrap(),
9176            AuthStatusResponse::new(AuthState::Unknown)
9177        );
9178    }
9179
9180    #[cfg(feature = "unstable_auth_status")]
9181    #[test]
9182    fn auth_status_update_notification_routes() {
9183        use crate::v1::{AgentNotification, CLIENT_METHOD_NAMES};
9184
9185        assert_eq!(AGENT_METHOD_NAMES.auth_status, "auth/status");
9186        assert_eq!(CLIENT_METHOD_NAMES.auth_status_update, "auth/status_update");
9187        let notification = AgentNotification::AuthStatusUpdateNotification(
9188            AuthStatusUpdateNotification::new(AuthState::Unauthenticated),
9189        );
9190        assert_eq!(notification.method(), "auth/status_update");
9191        assert_eq!(
9192            serde_json::to_value(&notification).unwrap(),
9193            json!({"state": "unauthenticated"})
9194        );
9195    }
9196
9197    #[cfg(all(
9198        feature = "unstable_session_fork",
9199        feature = "unstable_session_cursors"
9200    ))]
9201    #[test]
9202    fn fork_session_request_cursor_id_is_optional_and_strict() {
9203        let request = ForkSessionRequest::new("sess_abc123", "/home/user/project")
9204            .cursor_id(CursorId::new("cur_1"));
9205        let wire = json!({
9206            "sessionId": "sess_abc123",
9207            "cursorId": "cur_1",
9208            "cwd": "/home/user/project"
9209        });
9210        assert_eq!(serde_json::to_value(&request).unwrap(), wire);
9211        assert_eq!(
9212            serde_json::from_value::<ForkSessionRequest>(wire).unwrap(),
9213            request
9214        );
9215
9216        // Omitted and `null` both fork the whole session.
9217        for wire in [
9218            json!({ "sessionId": "sess_abc123", "cwd": "/home/user/project" }),
9219            json!({ "sessionId": "sess_abc123", "cwd": "/home/user/project", "cursorId": null }),
9220        ] {
9221            assert_eq!(
9222                serde_json::from_value::<ForkSessionRequest>(wire)
9223                    .unwrap()
9224                    .cursor_id,
9225                None
9226            );
9227        }
9228
9229        // A malformed cursor ID fails the request. It never forks the whole session.
9230        assert!(
9231            serde_json::from_value::<ForkSessionRequest>(json!({
9232                "sessionId": "sess_abc123",
9233                "cwd": "/home/user/project",
9234                "cursorId": 7
9235            }))
9236            .is_err()
9237        );
9238    }
9239}