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]
4983#[expect(clippy::doc_markdown)]
4984pub enum LlmProtocol {
4985    /// Anthropic API protocol.
4986    Anthropic,
4987    /// OpenAI API protocol.
4988    #[serde(rename = "openai")]
4989    OpenAi,
4990    /// Azure OpenAI API protocol.
4991    Azure,
4992    /// Google Vertex AI API protocol.
4993    Vertex,
4994    /// AWS Bedrock API protocol.
4995    Bedrock,
4996    /// Unknown or custom protocol.
4997    #[serde(untagged)]
4998    Other(String),
4999}
5000
5001/// **UNSTABLE**
5002///
5003/// This capability is not part of the spec yet, and may be removed or changed at any point.
5004///
5005/// Current effective non-secret routing configuration for a provider.
5006#[cfg(feature = "unstable_llm_providers")]
5007#[serde_as]
5008#[skip_serializing_none]
5009#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5010#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
5011#[serde(rename_all = "camelCase")]
5012#[non_exhaustive]
5013pub struct ProviderCurrentConfig {
5014    /// Protocol currently used by this provider.
5015    pub api_type: LlmProtocol,
5016    /// Base URL currently used by this provider.
5017    pub base_url: String,
5018    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5019    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5020    /// these keys.
5021    ///
5022    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5023    #[serde_as(deserialize_as = "DefaultOnError")]
5024    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5025    #[serde(default)]
5026    #[serde(rename = "_meta")]
5027    pub meta: Option<Meta>,
5028}
5029
5030#[cfg(feature = "unstable_llm_providers")]
5031impl ProviderCurrentConfig {
5032    /// Builds [`ProviderCurrentConfig`] with the required fields set. Optional fields start unset or empty.
5033    #[must_use]
5034    pub fn new(api_type: LlmProtocol, base_url: impl Into<String>) -> Self {
5035        Self {
5036            api_type,
5037            base_url: base_url.into(),
5038            meta: None,
5039        }
5040    }
5041
5042    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5043    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5044    /// these keys.
5045    ///
5046    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5047    #[must_use]
5048    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5049        self.meta = meta.into_option();
5050        self
5051    }
5052}
5053
5054/// **UNSTABLE**
5055///
5056/// This capability is not part of the spec yet, and may be removed or changed at any point.
5057///
5058/// Unique identifier for a configurable LLM provider.
5059#[cfg(feature = "unstable_llm_providers")]
5060#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5061#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash, Display, From)]
5062#[serde(transparent)]
5063#[from(Arc<str>, String, &'static str)]
5064#[non_exhaustive]
5065pub struct ProviderId(pub Arc<str>);
5066
5067#[cfg(feature = "unstable_llm_providers")]
5068impl ProviderId {
5069    /// Wraps a protocol string as a typed [`ProviderId`].
5070    #[must_use]
5071    pub fn new(id: impl Into<Arc<str>>) -> Self {
5072        Self(id.into())
5073    }
5074}
5075
5076/// **UNSTABLE**
5077///
5078/// This capability is not part of the spec yet, and may be removed or changed at any point.
5079///
5080/// Information about a configurable LLM provider.
5081#[cfg(feature = "unstable_llm_providers")]
5082#[serde_as]
5083#[skip_serializing_none]
5084#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5085#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
5086#[serde(rename_all = "camelCase")]
5087#[non_exhaustive]
5088pub struct ProviderInfo {
5089    /// Provider identifier, for example "main" or "openai".
5090    pub provider_id: ProviderId,
5091    /// Supported protocol types for this provider.
5092    #[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_>>")]
5093    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
5094    pub supported: Vec<LlmProtocol>,
5095    /// Whether this provider is mandatory and cannot be disabled via `providers/disable`.
5096    /// If true, clients MUST NOT call `providers/disable` for this provider ID.
5097    pub required: bool,
5098    /// Current effective non-secret routing config.
5099    /// Null or omitted means provider is disabled.
5100    #[serde(default)]
5101    pub current: Option<ProviderCurrentConfig>,
5102    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5103    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5104    /// these keys.
5105    ///
5106    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5107    #[serde_as(deserialize_as = "DefaultOnError")]
5108    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5109    #[serde(default)]
5110    #[serde(rename = "_meta")]
5111    pub meta: Option<Meta>,
5112}
5113
5114#[cfg(feature = "unstable_llm_providers")]
5115impl ProviderInfo {
5116    /// Builds [`ProviderInfo`] with the required fields set. Optional fields start unset or empty.
5117    #[must_use]
5118    pub fn new(
5119        provider_id: impl Into<ProviderId>,
5120        supported: Vec<LlmProtocol>,
5121        required: bool,
5122        current: impl IntoOption<ProviderCurrentConfig>,
5123    ) -> Self {
5124        Self {
5125            provider_id: provider_id.into(),
5126            supported,
5127            required,
5128            current: current.into_option(),
5129            meta: None,
5130        }
5131    }
5132
5133    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5134    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5135    /// these keys.
5136    ///
5137    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5138    #[must_use]
5139    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5140        self.meta = meta.into_option();
5141        self
5142    }
5143}
5144
5145#[cfg(feature = "unstable_llm_providers")]
5146crate::serde_util::default_on_null! {
5147    /// **UNSTABLE**
5148    ///
5149    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5150    ///
5151    /// Request parameters for `providers/list`.
5152    #[serde_as]
5153    #[skip_serializing_none]
5154    #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5155    #[derive(Default, Debug, Clone, Serialize, PartialEq, Eq)]
5156    #[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = PROVIDERS_LIST_METHOD_NAME)))]
5157    #[serde(rename_all = "camelCase")]
5158    #[non_exhaustive]
5159    pub struct ListProvidersRequest {
5160        /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5161        /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5162        /// these keys.
5163        ///
5164        /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5165        #[serde_as(deserialize_as = "DefaultOnError")]
5166        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5167        #[serde(default)]
5168        #[serde(rename = "_meta")]
5169        pub meta: Option<Meta>,
5170    }
5171}
5172
5173#[cfg(feature = "unstable_llm_providers")]
5174impl ListProvidersRequest {
5175    /// Builds [`ListProvidersRequest`] with the required request fields set. Optional fields start unset or empty.
5176    #[must_use]
5177    pub fn new() -> Self {
5178        Self::default()
5179    }
5180
5181    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5182    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5183    /// these keys.
5184    ///
5185    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5186    #[must_use]
5187    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5188        self.meta = meta.into_option();
5189        self
5190    }
5191}
5192
5193/// **UNSTABLE**
5194///
5195/// This capability is not part of the spec yet, and may be removed or changed at any point.
5196///
5197/// Response to `providers/list`.
5198#[cfg(feature = "unstable_llm_providers")]
5199#[serde_as]
5200#[skip_serializing_none]
5201#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5202#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
5203#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = PROVIDERS_LIST_METHOD_NAME)))]
5204#[serde(rename_all = "camelCase")]
5205#[non_exhaustive]
5206pub struct ListProvidersResponse {
5207    /// Configurable providers with current routing info suitable for UI display.
5208    pub providers: Vec<ProviderInfo>,
5209    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5210    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5211    /// these keys.
5212    ///
5213    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5214    #[serde_as(deserialize_as = "DefaultOnError")]
5215    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5216    #[serde(default)]
5217    #[serde(rename = "_meta")]
5218    pub meta: Option<Meta>,
5219}
5220
5221#[cfg(feature = "unstable_llm_providers")]
5222impl ListProvidersResponse {
5223    /// Builds [`ListProvidersResponse`] with the required response fields set. Optional fields start unset or empty.
5224    #[must_use]
5225    pub fn new(providers: Vec<ProviderInfo>) -> Self {
5226        Self {
5227            providers,
5228            meta: None,
5229        }
5230    }
5231
5232    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5233    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5234    /// these keys.
5235    ///
5236    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5237    #[must_use]
5238    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5239        self.meta = meta.into_option();
5240        self
5241    }
5242}
5243
5244/// **UNSTABLE**
5245///
5246/// This capability is not part of the spec yet, and may be removed or changed at any point.
5247///
5248/// Request parameters for `providers/set`.
5249///
5250/// Replaces the full configuration for one provider ID.
5251#[cfg(feature = "unstable_llm_providers")]
5252#[serde_as]
5253#[skip_serializing_none]
5254#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5255#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
5256#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = PROVIDERS_SET_METHOD_NAME)))]
5257#[serde(rename_all = "camelCase")]
5258#[non_exhaustive]
5259pub struct SetProviderRequest {
5260    /// Provider ID to configure.
5261    pub provider_id: ProviderId,
5262    /// Protocol type for this provider.
5263    pub api_type: LlmProtocol,
5264    /// Base URL for requests sent through this provider.
5265    pub base_url: String,
5266    /// Full headers map for this provider.
5267    /// May include authorization, routing, or other integration-specific headers.
5268    #[serde(default, skip_serializing_if = "IndexMap::is_empty")]
5269    pub headers: IndexMap<String, String>,
5270    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5271    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5272    /// these keys.
5273    ///
5274    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5275    #[serde_as(deserialize_as = "DefaultOnError")]
5276    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5277    #[serde(default)]
5278    #[serde(rename = "_meta")]
5279    pub meta: Option<Meta>,
5280}
5281
5282#[cfg(feature = "unstable_llm_providers")]
5283impl SetProviderRequest {
5284    /// Builds [`SetProviderRequest`] with the required request fields set. Optional fields start unset or empty.
5285    #[must_use]
5286    pub fn new(
5287        provider_id: impl Into<ProviderId>,
5288        api_type: LlmProtocol,
5289        base_url: impl Into<String>,
5290    ) -> Self {
5291        Self {
5292            provider_id: provider_id.into(),
5293            api_type,
5294            base_url: base_url.into(),
5295            headers: IndexMap::new(),
5296            meta: None,
5297        }
5298    }
5299
5300    /// Full headers map for this provider.
5301    /// May include authorization, routing, or other integration-specific headers.
5302    #[must_use]
5303    pub fn headers(mut self, headers: IndexMap<String, String>) -> Self {
5304        self.headers = headers;
5305        self
5306    }
5307
5308    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5309    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5310    /// these keys.
5311    ///
5312    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5313    #[must_use]
5314    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5315        self.meta = meta.into_option();
5316        self
5317    }
5318}
5319
5320#[cfg(feature = "unstable_llm_providers")]
5321crate::serde_util::default_on_null! {
5322    /// **UNSTABLE**
5323    ///
5324    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5325    ///
5326    /// Response to `providers/set`.
5327    #[serde_as]
5328    #[skip_serializing_none]
5329    #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5330    #[derive(Default, Debug, Clone, Serialize, PartialEq, Eq)]
5331    #[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = PROVIDERS_SET_METHOD_NAME)))]
5332    #[serde(rename_all = "camelCase")]
5333    #[non_exhaustive]
5334    pub struct SetProviderResponse {
5335        /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5336        /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5337        /// these keys.
5338        ///
5339        /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5340        #[serde_as(deserialize_as = "DefaultOnError")]
5341        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5342        #[serde(default)]
5343        #[serde(rename = "_meta")]
5344        pub meta: Option<Meta>,
5345    }
5346}
5347
5348#[cfg(feature = "unstable_llm_providers")]
5349impl SetProviderResponse {
5350    /// Builds [`SetProviderResponse`] with the required response fields set. Optional fields start unset or empty.
5351    #[must_use]
5352    pub fn new() -> Self {
5353        Self::default()
5354    }
5355
5356    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5357    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5358    /// these keys.
5359    ///
5360    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5361    #[must_use]
5362    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5363        self.meta = meta.into_option();
5364        self
5365    }
5366}
5367
5368/// **UNSTABLE**
5369///
5370/// This capability is not part of the spec yet, and may be removed or changed at any point.
5371///
5372/// Request parameters for `providers/disable`.
5373#[cfg(feature = "unstable_llm_providers")]
5374#[serde_as]
5375#[skip_serializing_none]
5376#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5377#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
5378#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = PROVIDERS_DISABLE_METHOD_NAME)))]
5379#[serde(rename_all = "camelCase")]
5380#[non_exhaustive]
5381pub struct DisableProviderRequest {
5382    /// Provider ID to disable.
5383    pub provider_id: ProviderId,
5384    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5385    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5386    /// these keys.
5387    ///
5388    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5389    #[serde_as(deserialize_as = "DefaultOnError")]
5390    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5391    #[serde(default)]
5392    #[serde(rename = "_meta")]
5393    pub meta: Option<Meta>,
5394}
5395
5396#[cfg(feature = "unstable_llm_providers")]
5397impl DisableProviderRequest {
5398    /// Builds [`DisableProviderRequest`] with the required request fields set. Optional fields start unset or empty.
5399    #[must_use]
5400    pub fn new(provider_id: impl Into<ProviderId>) -> Self {
5401        Self {
5402            provider_id: provider_id.into(),
5403            meta: None,
5404        }
5405    }
5406
5407    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5408    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5409    /// these keys.
5410    ///
5411    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5412    #[must_use]
5413    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5414        self.meta = meta.into_option();
5415        self
5416    }
5417}
5418
5419#[cfg(feature = "unstable_llm_providers")]
5420crate::serde_util::default_on_null! {
5421    /// **UNSTABLE**
5422    ///
5423    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5424    ///
5425    /// Response to `providers/disable`.
5426    #[serde_as]
5427    #[skip_serializing_none]
5428    #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5429    #[derive(Default, Debug, Clone, Serialize, PartialEq, Eq)]
5430    #[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = PROVIDERS_DISABLE_METHOD_NAME)))]
5431    #[serde(rename_all = "camelCase")]
5432    #[non_exhaustive]
5433    pub struct DisableProviderResponse {
5434        /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5435        /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5436        /// these keys.
5437        ///
5438        /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5439        #[serde_as(deserialize_as = "DefaultOnError")]
5440        #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5441        #[serde(default)]
5442        #[serde(rename = "_meta")]
5443        pub meta: Option<Meta>,
5444    }
5445}
5446
5447#[cfg(feature = "unstable_llm_providers")]
5448impl DisableProviderResponse {
5449    /// Builds [`DisableProviderResponse`] with the required response fields set. Optional fields start unset or empty.
5450    #[must_use]
5451    pub fn new() -> Self {
5452        Self::default()
5453    }
5454
5455    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5456    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5457    /// these keys.
5458    ///
5459    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5460    #[must_use]
5461    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5462        self.meta = meta.into_option();
5463        self
5464    }
5465}
5466
5467// Capabilities
5468
5469/// Capabilities supported by the agent.
5470///
5471/// Advertised during initialization to inform the client about
5472/// available features and content types.
5473///
5474/// See protocol docs: [Agent Capabilities](https://agentclientprotocol.com/protocol/v1/initialization#agent-capabilities)
5475#[serde_as]
5476#[skip_serializing_none]
5477#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5478#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
5479#[serde(rename_all = "camelCase")]
5480#[non_exhaustive]
5481pub struct AgentCapabilities {
5482    /// Whether the agent supports `session/load`.
5483    #[serde_as(deserialize_as = "DefaultOnError")]
5484    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5485    #[serde(default)]
5486    pub load_session: bool,
5487    /// Prompt capabilities supported by the agent.
5488    #[serde_as(deserialize_as = "DefaultOnError")]
5489    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5490    #[serde(default)]
5491    pub prompt_capabilities: PromptCapabilities,
5492    /// MCP capabilities supported by the agent.
5493    #[serde_as(deserialize_as = "DefaultOnError")]
5494    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5495    #[serde(default)]
5496    pub mcp_capabilities: McpCapabilities,
5497    /// Session lifecycle and prompt capabilities advertised by the agent.
5498    #[serde_as(deserialize_as = "DefaultOnError")]
5499    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5500    #[serde(default)]
5501    pub session_capabilities: SessionCapabilities,
5502    /// Authentication-related capabilities supported by the agent.
5503    #[serde_as(deserialize_as = "DefaultOnError")]
5504    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5505    #[serde(default)]
5506    pub auth: AgentAuthCapabilities,
5507    /// **UNSTABLE**
5508    ///
5509    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5510    ///
5511    /// Provider configuration capabilities supported by the agent.
5512    ///
5513    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5514    /// Supplying `{}` means the agent supports provider configuration methods.
5515    #[cfg(feature = "unstable_llm_providers")]
5516    #[serde_as(deserialize_as = "DefaultOnError")]
5517    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5518    #[serde(default)]
5519    pub providers: Option<ProvidersCapabilities>,
5520    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5521    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5522    /// these keys.
5523    ///
5524    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5525    #[serde_as(deserialize_as = "DefaultOnError")]
5526    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5527    #[serde(default)]
5528    #[serde(rename = "_meta")]
5529    pub meta: Option<Meta>,
5530}
5531
5532impl AgentCapabilities {
5533    /// Builds an empty [`AgentCapabilities`]. Use builder methods to advertise supported sub-capabilities.
5534    #[must_use]
5535    pub fn new() -> Self {
5536        Self::default()
5537    }
5538
5539    /// Whether the agent supports `session/load`.
5540    #[must_use]
5541    pub fn load_session(mut self, load_session: bool) -> Self {
5542        self.load_session = load_session;
5543        self
5544    }
5545
5546    /// Prompt capabilities supported by the agent.
5547    #[must_use]
5548    pub fn prompt_capabilities(mut self, prompt_capabilities: PromptCapabilities) -> Self {
5549        self.prompt_capabilities = prompt_capabilities;
5550        self
5551    }
5552
5553    /// MCP capabilities supported by the agent.
5554    #[must_use]
5555    pub fn mcp_capabilities(mut self, mcp_capabilities: McpCapabilities) -> Self {
5556        self.mcp_capabilities = mcp_capabilities;
5557        self
5558    }
5559
5560    /// Session capabilities supported by the agent.
5561    #[must_use]
5562    pub fn session_capabilities(mut self, session_capabilities: SessionCapabilities) -> Self {
5563        self.session_capabilities = session_capabilities;
5564        self
5565    }
5566
5567    /// Authentication-related capabilities supported by the agent.
5568    #[must_use]
5569    pub fn auth(mut self, auth: AgentAuthCapabilities) -> Self {
5570        self.auth = auth;
5571        self
5572    }
5573
5574    /// **UNSTABLE**
5575    ///
5576    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5577    ///
5578    /// Provider configuration capabilities supported by the agent.
5579    #[cfg(feature = "unstable_llm_providers")]
5580    #[must_use]
5581    pub fn providers(mut self, providers: impl IntoOption<ProvidersCapabilities>) -> Self {
5582        self.providers = providers.into_option();
5583        self
5584    }
5585
5586    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5587    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5588    /// these keys.
5589    ///
5590    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5591    #[must_use]
5592    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5593        self.meta = meta.into_option();
5594        self
5595    }
5596}
5597
5598/// **UNSTABLE**
5599///
5600/// This capability is not part of the spec yet, and may be removed or changed at any point.
5601///
5602/// Provider configuration capabilities supported by the agent.
5603///
5604/// Supplying `{}` means the agent supports provider configuration methods.
5605#[cfg(feature = "unstable_llm_providers")]
5606#[serde_as]
5607#[skip_serializing_none]
5608#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5609#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
5610#[non_exhaustive]
5611pub struct ProvidersCapabilities {
5612    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5613    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5614    /// these keys.
5615    ///
5616    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5617    #[serde_as(deserialize_as = "DefaultOnError")]
5618    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5619    #[serde(default)]
5620    #[serde(rename = "_meta")]
5621    pub meta: Option<Meta>,
5622}
5623
5624#[cfg(feature = "unstable_llm_providers")]
5625impl ProvidersCapabilities {
5626    /// Builds an empty [`ProvidersCapabilities`]. Use builder methods to advertise supported sub-capabilities.
5627    #[must_use]
5628    pub fn new() -> Self {
5629        Self::default()
5630    }
5631
5632    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5633    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5634    /// these keys.
5635    ///
5636    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5637    #[must_use]
5638    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5639        self.meta = meta.into_option();
5640        self
5641    }
5642}
5643
5644/// Session capabilities supported by the agent.
5645///
5646/// As a baseline, all Agents **MUST** support `session/new`, `session/prompt`, `session/cancel`, and `session/update`.
5647///
5648/// Optionally, they **MAY** support other session methods and notifications by specifying additional capabilities.
5649///
5650/// Note: `session/load` is still handled by the top-level `loadSession` capability. This will be unified in future versions of the protocol.
5651///
5652/// See protocol docs: [Session Capabilities](https://agentclientprotocol.com/protocol/v1/initialization#session-capabilities)
5653#[serde_as]
5654#[skip_serializing_none]
5655#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5656#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
5657#[serde(rename_all = "camelCase")]
5658#[non_exhaustive]
5659pub struct SessionCapabilities {
5660    /// Whether the agent supports `session/list`.
5661    ///
5662    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5663    /// Supplying `{}` means the agent supports listing sessions.
5664    #[serde_as(deserialize_as = "DefaultOnError")]
5665    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5666    #[serde(default)]
5667    pub list: Option<SessionListCapabilities>,
5668    /// Whether the agent supports `session/delete`.
5669    ///
5670    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5671    /// Supplying `{}` means the agent supports deleting sessions from `session/list`.
5672    #[serde_as(deserialize_as = "DefaultOnError")]
5673    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5674    #[serde(default)]
5675    pub delete: Option<SessionDeleteCapabilities>,
5676    /// Whether the agent supports `additionalDirectories` on supported session lifecycle requests.
5677    ///
5678    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5679    /// Supplying `{}` means the agent supports `additionalDirectories` on
5680    /// supported session lifecycle requests.
5681    ///
5682    /// Agents that also support `session/list` may return
5683    /// `SessionInfo.additionalDirectories` to report the complete ordered
5684    /// additional-root list associated with a listed session.
5685    #[serde_as(deserialize_as = "DefaultOnError")]
5686    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5687    #[serde(default)]
5688    pub additional_directories: Option<SessionAdditionalDirectoriesCapabilities>,
5689    /// Whether the agent supports `systemPrompt` on session lifecycle requests.
5690    ///
5691    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5692    /// Supplying `{}` means the agent supports `systemPrompt` in `append` mode.
5693    #[serde_as(deserialize_as = "DefaultOnError")]
5694    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5695    #[serde(default)]
5696    pub system_prompt: Option<SessionSystemPromptCapabilities>,
5697    /// **UNSTABLE**
5698    ///
5699    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5700    ///
5701    /// Whether the agent supports `session/fork`.
5702    ///
5703    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5704    /// Supplying `{}` means the agent supports forking sessions.
5705    #[cfg(feature = "unstable_session_fork")]
5706    #[serde_as(deserialize_as = "DefaultOnError")]
5707    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5708    #[serde(default)]
5709    pub fork: Option<SessionForkCapabilities>,
5710    /// **UNSTABLE**
5711    ///
5712    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5713    ///
5714    /// Whether the agent supports `session/archive` and `session/unarchive`.
5715    ///
5716    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5717    /// Supplying `{}` means the agent supports both methods, the `archived` filter on
5718    /// `session/list`, and `SessionInfo.archived`. Agents that advertise it MUST also advertise `sessionCapabilities.list`.
5719    #[cfg(feature = "unstable_session_archive")]
5720    #[serde_as(deserialize_as = "DefaultOnError")]
5721    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5722    #[serde(default)]
5723    pub archive: Option<SessionArchiveCapabilities>,
5724    /// **UNSTABLE**
5725    ///
5726    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5727    ///
5728    /// Whether the agent supports `session/status`.
5729    ///
5730    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5731    /// Supplying `{}` means the agent supports checking session status.
5732    #[cfg(feature = "unstable_session_status")]
5733    #[serde_as(deserialize_as = "DefaultOnError")]
5734    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5735    #[serde(default)]
5736    pub status: Option<SessionStatusCapabilities>,
5737    /// **UNSTABLE**
5738    ///
5739    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5740    ///
5741    /// Whether the agent supports `session/options`.
5742    ///
5743    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5744    /// Supplying `{}` means the agent supports `session/options` and accepts initial
5745    /// config option values on session setup requests.
5746    #[cfg(feature = "unstable_session_options")]
5747    #[serde_as(deserialize_as = "DefaultOnError")]
5748    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5749    #[serde(default)]
5750    pub options: Option<SessionOptionsCapabilities>,
5751    /// **UNSTABLE**
5752    ///
5753    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5754    ///
5755    /// Whether the agent supports `session/set_title`.
5756    ///
5757    /// Agents report titles through `session/list` and `session_info_update` without this
5758    /// capability. It only advertises that Clients can set titles.
5759    ///
5760    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5761    /// Supplying `{}` means the agent supports setting session titles.
5762    #[cfg(feature = "unstable_session_set_title")]
5763    #[serde_as(deserialize_as = "DefaultOnError")]
5764    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5765    #[serde(default)]
5766    pub title: Option<SessionTitleCapabilities>,
5767    /// Whether the agent supports `session/resume`.
5768    ///
5769    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5770    /// Supplying `{}` means the agent supports resuming sessions.
5771    #[serde_as(deserialize_as = "DefaultOnError")]
5772    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5773    #[serde(default)]
5774    pub resume: Option<SessionResumeCapabilities>,
5775    /// Whether the agent supports `session/close`.
5776    ///
5777    /// Optional. Omitted or `null` both mean the agent does not advertise support.
5778    /// Supplying `{}` means the agent supports closing sessions.
5779    #[serde_as(deserialize_as = "DefaultOnError")]
5780    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5781    #[serde(default)]
5782    pub close: Option<SessionCloseCapabilities>,
5783    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5784    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5785    /// these keys.
5786    ///
5787    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5788    #[serde_as(deserialize_as = "DefaultOnError")]
5789    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5790    #[serde(default)]
5791    #[serde(rename = "_meta")]
5792    pub meta: Option<Meta>,
5793}
5794
5795impl SessionCapabilities {
5796    /// Builds an empty [`SessionCapabilities`]. Use builder methods to advertise supported sub-capabilities.
5797    #[must_use]
5798    pub fn new() -> Self {
5799        Self::default()
5800    }
5801
5802    /// Whether the agent supports `session/list`.
5803    ///
5804    /// Omitted or `null` both mean the agent does not advertise support.
5805    /// Supplying `{}` means the agent supports listing sessions.
5806    #[must_use]
5807    pub fn list(mut self, list: impl IntoOption<SessionListCapabilities>) -> Self {
5808        self.list = list.into_option();
5809        self
5810    }
5811
5812    /// Whether the agent supports `session/delete`.
5813    ///
5814    /// Omitted or `null` both mean the agent does not advertise support.
5815    /// Supplying `{}` means the agent supports deleting sessions from `session/list`.
5816    #[must_use]
5817    pub fn delete(mut self, delete: impl IntoOption<SessionDeleteCapabilities>) -> Self {
5818        self.delete = delete.into_option();
5819        self
5820    }
5821
5822    /// Whether the agent supports `additionalDirectories` on supported session lifecycle requests.
5823    ///
5824    /// Omitted or `null` both mean the agent does not advertise support.
5825    /// Supplying `{}` means the agent supports `additionalDirectories` on
5826    /// supported session lifecycle requests.
5827    ///
5828    /// Agents that also support `session/list` may return
5829    /// `SessionInfo.additionalDirectories` to report the complete ordered
5830    /// additional-root list associated with a listed session.
5831    #[must_use]
5832    pub fn additional_directories(
5833        mut self,
5834        additional_directories: impl IntoOption<SessionAdditionalDirectoriesCapabilities>,
5835    ) -> Self {
5836        self.additional_directories = additional_directories.into_option();
5837        self
5838    }
5839
5840    /// Whether the agent supports `systemPrompt` on session lifecycle requests.
5841    ///
5842    /// Omitted or `null` both mean the agent does not advertise support.
5843    /// Supplying `{}` means the agent supports `systemPrompt` in `append` mode.
5844    #[must_use]
5845    pub fn system_prompt(
5846        mut self,
5847        system_prompt: impl IntoOption<SessionSystemPromptCapabilities>,
5848    ) -> Self {
5849        self.system_prompt = system_prompt.into_option();
5850        self
5851    }
5852
5853    #[cfg(feature = "unstable_session_fork")]
5854    /// Whether the agent supports `session/fork`.
5855    ///
5856    /// Omitted or `null` both mean the agent does not advertise support.
5857    /// Supplying `{}` means the agent supports forking sessions.
5858    #[must_use]
5859    pub fn fork(mut self, fork: impl IntoOption<SessionForkCapabilities>) -> Self {
5860        self.fork = fork.into_option();
5861        self
5862    }
5863
5864    /// **UNSTABLE**
5865    ///
5866    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5867    ///
5868    /// Whether the agent supports `session/archive` and `session/unarchive`.
5869    ///
5870    /// Omitted or `null` both mean the agent does not advertise support.
5871    /// Supplying `{}` means the agent supports both methods, the `archived` filter on
5872    /// `session/list`, and `SessionInfo.archived`.
5873    #[cfg(feature = "unstable_session_archive")]
5874    #[must_use]
5875    pub fn archive(mut self, archive: impl IntoOption<SessionArchiveCapabilities>) -> Self {
5876        self.archive = archive.into_option();
5877        self
5878    }
5879
5880    /// **UNSTABLE**
5881    ///
5882    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5883    ///
5884    /// Whether the agent supports `session/status`.
5885    ///
5886    /// Omitted or `null` both mean the agent does not advertise support.
5887    /// Supplying `{}` means the agent supports checking session status.
5888    #[cfg(feature = "unstable_session_status")]
5889    #[must_use]
5890    pub fn status(mut self, status: impl IntoOption<SessionStatusCapabilities>) -> Self {
5891        self.status = status.into_option();
5892        self
5893    }
5894
5895    /// **UNSTABLE**
5896    ///
5897    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5898    ///
5899    /// Whether the agent supports `session/options`.
5900    ///
5901    /// Omitted or `null` both mean the agent does not advertise support.
5902    /// Supplying `{}` means the agent supports `session/options` and accepts initial
5903    /// config option values on session setup requests.
5904    #[cfg(feature = "unstable_session_options")]
5905    #[must_use]
5906    pub fn options(mut self, options: impl IntoOption<SessionOptionsCapabilities>) -> Self {
5907        self.options = options.into_option();
5908        self
5909    }
5910
5911    /// **UNSTABLE**
5912    ///
5913    /// This capability is not part of the spec yet, and may be removed or changed at any point.
5914    ///
5915    /// Whether the agent supports `session/set_title`.
5916    ///
5917    /// Agents report titles through `session/list` and `session_info_update` without this
5918    /// capability. It only advertises that Clients can set titles.
5919    ///
5920    /// Omitted or `null` both mean the agent does not advertise support.
5921    /// Supplying `{}` means the agent supports setting session titles.
5922    #[cfg(feature = "unstable_session_set_title")]
5923    #[must_use]
5924    pub fn title(mut self, title: impl IntoOption<SessionTitleCapabilities>) -> Self {
5925        self.title = title.into_option();
5926        self
5927    }
5928
5929    /// Whether the agent supports `session/resume`.
5930    ///
5931    /// Omitted or `null` both mean the agent does not advertise support.
5932    /// Supplying `{}` means the agent supports resuming sessions.
5933    #[must_use]
5934    pub fn resume(mut self, resume: impl IntoOption<SessionResumeCapabilities>) -> Self {
5935        self.resume = resume.into_option();
5936        self
5937    }
5938
5939    /// Whether the agent supports `session/close`.
5940    ///
5941    /// Omitted or `null` both mean the agent does not advertise support.
5942    /// Supplying `{}` means the agent supports closing sessions.
5943    #[must_use]
5944    pub fn close(mut self, close: impl IntoOption<SessionCloseCapabilities>) -> Self {
5945        self.close = close.into_option();
5946        self
5947    }
5948
5949    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5950    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5951    /// these keys.
5952    ///
5953    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5954    #[must_use]
5955    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5956        self.meta = meta.into_option();
5957        self
5958    }
5959}
5960
5961/// Capabilities for the `session/list` method.
5962///
5963/// Supplying `{}` means the agent supports listing sessions.
5964#[serde_as]
5965#[skip_serializing_none]
5966#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
5967#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
5968#[non_exhaustive]
5969pub struct SessionListCapabilities {
5970    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5971    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5972    /// these keys.
5973    ///
5974    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5975    #[serde_as(deserialize_as = "DefaultOnError")]
5976    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
5977    #[serde(default)]
5978    #[serde(rename = "_meta")]
5979    pub meta: Option<Meta>,
5980}
5981
5982impl SessionListCapabilities {
5983    /// Builds an empty [`SessionListCapabilities`]. Use builder methods to advertise supported sub-capabilities.
5984    #[must_use]
5985    pub fn new() -> Self {
5986        Self::default()
5987    }
5988
5989    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
5990    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
5991    /// these keys.
5992    ///
5993    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
5994    #[must_use]
5995    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
5996        self.meta = meta.into_option();
5997        self
5998    }
5999}
6000
6001/// Capabilities for the `session/delete` method.
6002///
6003/// Supplying `{}` means the agent supports deleting sessions from `session/list`.
6004#[serde_as]
6005#[skip_serializing_none]
6006#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6007#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6008#[non_exhaustive]
6009pub struct SessionDeleteCapabilities {
6010    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6011    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6012    /// these keys.
6013    ///
6014    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6015    #[serde_as(deserialize_as = "DefaultOnError")]
6016    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6017    #[serde(default)]
6018    #[serde(rename = "_meta")]
6019    pub meta: Option<Meta>,
6020}
6021
6022impl SessionDeleteCapabilities {
6023    /// Builds an empty [`SessionDeleteCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6024    #[must_use]
6025    pub fn new() -> Self {
6026        Self::default()
6027    }
6028
6029    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6030    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6031    /// these keys.
6032    ///
6033    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6034    #[must_use]
6035    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6036        self.meta = meta.into_option();
6037        self
6038    }
6039}
6040
6041/// Capabilities for additional session directories support.
6042///
6043/// Supplying `{}` means the agent supports the `additionalDirectories` field on
6044/// supported session lifecycle requests. Agents that also support
6045/// `session/list` may return `SessionInfo.additionalDirectories` to report the
6046/// complete ordered additional-root list associated with a listed session.
6047#[serde_as]
6048#[skip_serializing_none]
6049#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6050#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6051#[non_exhaustive]
6052pub struct SessionAdditionalDirectoriesCapabilities {
6053    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6054    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6055    /// these keys.
6056    ///
6057    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6058    #[serde_as(deserialize_as = "DefaultOnError")]
6059    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6060    #[serde(default)]
6061    #[serde(rename = "_meta")]
6062    pub meta: Option<Meta>,
6063}
6064
6065impl SessionAdditionalDirectoriesCapabilities {
6066    /// Builds an empty [`SessionAdditionalDirectoriesCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6067    #[must_use]
6068    pub fn new() -> Self {
6069        Self::default()
6070    }
6071
6072    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6073    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6074    /// these keys.
6075    ///
6076    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6077    #[must_use]
6078    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6079        self.meta = meta.into_option();
6080        self
6081    }
6082}
6083
6084/// Capabilities for client-provided system prompts.
6085///
6086/// Supplying `{}` means the agent supports `systemPrompt` on session lifecycle
6087/// requests in `append` mode.
6088#[serde_as]
6089#[skip_serializing_none]
6090#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6091#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6092#[serde(rename_all = "camelCase")]
6093#[non_exhaustive]
6094pub struct SessionSystemPromptCapabilities {
6095    /// Delivery modes the agent supports in addition to `append`.
6096    ///
6097    /// Optional. Omitted or `null` both mean the agent supports only `append`.
6098    #[serde_as(deserialize_as = "DefaultOnError")]
6099    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6100    #[serde(default)]
6101    pub mode: Option<SessionSystemPromptModeCapabilities>,
6102    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6103    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6104    /// these keys.
6105    ///
6106    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6107    #[serde_as(deserialize_as = "DefaultOnError")]
6108    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6109    #[serde(default)]
6110    #[serde(rename = "_meta")]
6111    pub meta: Option<Meta>,
6112}
6113
6114impl SessionSystemPromptCapabilities {
6115    /// Builds an empty [`SessionSystemPromptCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6116    #[must_use]
6117    pub fn new() -> Self {
6118        Self::default()
6119    }
6120
6121    /// Delivery modes the agent supports in addition to `append`.
6122    ///
6123    /// Omitted or `null` both mean the agent supports only `append`.
6124    #[must_use]
6125    pub fn mode(mut self, mode: impl IntoOption<SessionSystemPromptModeCapabilities>) -> Self {
6126        self.mode = mode.into_option();
6127        self
6128    }
6129
6130    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6131    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6132    /// these keys.
6133    ///
6134    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6135    #[must_use]
6136    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6137        self.meta = meta.into_option();
6138        self
6139    }
6140}
6141
6142/// System prompt delivery modes the agent supports in addition to `append`.
6143///
6144/// `append` has no entry because every agent advertising
6145/// `sessionCapabilities.systemPrompt` supports it.
6146#[serde_as]
6147#[skip_serializing_none]
6148#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6149#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6150#[serde(rename_all = "camelCase")]
6151#[non_exhaustive]
6152pub struct SessionSystemPromptModeCapabilities {
6153    /// Whether the agent supports `override` mode.
6154    ///
6155    /// Optional. Omitted or `null` both mean the agent does not advertise support.
6156    /// Supplying `{}` means the agent supports replacing its built-in default
6157    /// instructions with the client-provided system prompt.
6158    #[serde_as(deserialize_as = "DefaultOnError")]
6159    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6160    #[serde(default, rename = "override")]
6161    pub override_: Option<SessionSystemPromptOverrideCapabilities>,
6162    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6163    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6164    /// these keys.
6165    ///
6166    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6167    #[serde_as(deserialize_as = "DefaultOnError")]
6168    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6169    #[serde(default)]
6170    #[serde(rename = "_meta")]
6171    pub meta: Option<Meta>,
6172}
6173
6174impl SessionSystemPromptModeCapabilities {
6175    /// Builds an empty [`SessionSystemPromptModeCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6176    #[must_use]
6177    pub fn new() -> Self {
6178        Self::default()
6179    }
6180
6181    /// Whether the agent supports `override` mode.
6182    ///
6183    /// Omitted or `null` both mean the agent does not advertise support.
6184    /// Supplying `{}` means the agent supports replacing its built-in default
6185    /// instructions with the client-provided system prompt.
6186    #[must_use]
6187    pub fn override_(
6188        mut self,
6189        override_: impl IntoOption<SessionSystemPromptOverrideCapabilities>,
6190    ) -> Self {
6191        self.override_ = override_.into_option();
6192        self
6193    }
6194
6195    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6196    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6197    /// these keys.
6198    ///
6199    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6200    #[must_use]
6201    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6202        self.meta = meta.into_option();
6203        self
6204    }
6205}
6206
6207/// Capabilities for the `override` system prompt mode.
6208///
6209/// Supplying `{}` means the agent supports replacing its built-in default
6210/// instructions with the client-provided system prompt.
6211#[serde_as]
6212#[skip_serializing_none]
6213#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6214#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6215#[non_exhaustive]
6216pub struct SessionSystemPromptOverrideCapabilities {
6217    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6218    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6219    /// these keys.
6220    ///
6221    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6222    #[serde_as(deserialize_as = "DefaultOnError")]
6223    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6224    #[serde(default)]
6225    #[serde(rename = "_meta")]
6226    pub meta: Option<Meta>,
6227}
6228
6229impl SessionSystemPromptOverrideCapabilities {
6230    /// Builds an empty [`SessionSystemPromptOverrideCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6231    #[must_use]
6232    pub fn new() -> Self {
6233        Self::default()
6234    }
6235
6236    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6237    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6238    /// these keys.
6239    ///
6240    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6241    #[must_use]
6242    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6243        self.meta = meta.into_option();
6244        self
6245    }
6246}
6247
6248/// **UNSTABLE**
6249///
6250/// This capability is not part of the spec yet, and may be removed or changed at any point.
6251///
6252/// Capabilities for the `session/fork` method.
6253///
6254/// Supplying `{}` means the agent supports forking sessions.
6255#[cfg(feature = "unstable_session_fork")]
6256#[serde_as]
6257#[skip_serializing_none]
6258#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6259#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6260#[non_exhaustive]
6261pub struct SessionForkCapabilities {
6262    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6263    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6264    /// these keys.
6265    ///
6266    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6267    #[serde_as(deserialize_as = "DefaultOnError")]
6268    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6269    #[serde(default)]
6270    #[serde(rename = "_meta")]
6271    pub meta: Option<Meta>,
6272}
6273
6274#[cfg(feature = "unstable_session_fork")]
6275impl SessionForkCapabilities {
6276    /// Builds an empty [`SessionForkCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6277    #[must_use]
6278    pub fn new() -> Self {
6279        Self::default()
6280    }
6281
6282    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6283    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6284    /// these keys.
6285    ///
6286    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6287    #[must_use]
6288    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6289        self.meta = meta.into_option();
6290        self
6291    }
6292}
6293
6294/// **UNSTABLE**
6295///
6296/// This capability is not part of the spec yet, and may be removed or changed at any point.
6297///
6298/// Capabilities for `session/archive` and `session/unarchive`.
6299///
6300/// Supplying `{}` means the agent supports both methods, the `archived` filter on
6301/// `session/list`, and `SessionInfo.archived`.
6302#[cfg(feature = "unstable_session_archive")]
6303#[serde_as]
6304#[skip_serializing_none]
6305#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6306#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6307#[non_exhaustive]
6308pub struct SessionArchiveCapabilities {
6309    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6310    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6311    /// these keys.
6312    ///
6313    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6314    #[serde_as(deserialize_as = "DefaultOnError")]
6315    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6316    #[serde(default)]
6317    #[serde(rename = "_meta")]
6318    pub meta: Option<Meta>,
6319}
6320
6321#[cfg(feature = "unstable_session_archive")]
6322impl SessionArchiveCapabilities {
6323    /// Builds an empty [`SessionArchiveCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6324    #[must_use]
6325    pub fn new() -> Self {
6326        Self::default()
6327    }
6328
6329    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6330    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6331    /// these keys.
6332    ///
6333    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6334    #[must_use]
6335    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6336        self.meta = meta.into_option();
6337        self
6338    }
6339}
6340
6341/// **UNSTABLE**
6342///
6343/// This capability is not part of the spec yet, and may be removed or changed at any point.
6344///
6345/// Capabilities for the `session/status` method.
6346///
6347/// Supplying `{}` means the agent supports checking session status.
6348#[cfg(feature = "unstable_session_status")]
6349#[serde_as]
6350#[skip_serializing_none]
6351#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6352#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6353#[non_exhaustive]
6354pub struct SessionStatusCapabilities {
6355    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6356    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6357    /// these keys.
6358    ///
6359    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6360    #[serde_as(deserialize_as = "DefaultOnError")]
6361    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6362    #[serde(default)]
6363    #[serde(rename = "_meta")]
6364    pub meta: Option<Meta>,
6365}
6366
6367#[cfg(feature = "unstable_session_status")]
6368impl SessionStatusCapabilities {
6369    /// Builds an empty [`SessionStatusCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6370    #[must_use]
6371    pub fn new() -> Self {
6372        Self::default()
6373    }
6374
6375    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6376    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6377    /// these keys.
6378    ///
6379    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6380    #[must_use]
6381    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6382        self.meta = meta.into_option();
6383        self
6384    }
6385}
6386
6387/// **UNSTABLE**
6388///
6389/// This capability is not part of the spec yet, and may be removed or changed at any point.
6390///
6391/// Capabilities for the `session/options` method.
6392///
6393/// Supplying `{}` means the agent supports `session/options` and accepts initial config
6394/// option values on session setup requests.
6395#[cfg(feature = "unstable_session_options")]
6396#[serde_as]
6397#[skip_serializing_none]
6398#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6399#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6400#[non_exhaustive]
6401pub struct SessionOptionsCapabilities {
6402    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6403    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6404    /// these keys.
6405    ///
6406    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6407    #[serde_as(deserialize_as = "DefaultOnError")]
6408    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6409    #[serde(default)]
6410    #[serde(rename = "_meta")]
6411    pub meta: Option<Meta>,
6412}
6413
6414#[cfg(feature = "unstable_session_options")]
6415impl SessionOptionsCapabilities {
6416    /// Builds an empty [`SessionOptionsCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6417    #[must_use]
6418    pub fn new() -> Self {
6419        Self::default()
6420    }
6421
6422    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6423    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6424    /// these keys.
6425    ///
6426    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6427    #[must_use]
6428    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6429        self.meta = meta.into_option();
6430        self
6431    }
6432}
6433
6434/// **UNSTABLE**
6435///
6436/// This capability is not part of the spec yet, and may be removed or changed at any point.
6437///
6438/// Capabilities for Client-set session titles.
6439///
6440/// Supplying `{}` means the agent supports `session/set_title`. Agents report titles
6441/// through `session/list` and `session_info_update` without this capability.
6442#[cfg(feature = "unstable_session_set_title")]
6443#[serde_as]
6444#[skip_serializing_none]
6445#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6446#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6447#[non_exhaustive]
6448pub struct SessionTitleCapabilities {
6449    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6450    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6451    /// these keys.
6452    ///
6453    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6454    #[serde_as(deserialize_as = "DefaultOnError")]
6455    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6456    #[serde(default)]
6457    #[serde(rename = "_meta")]
6458    pub meta: Option<Meta>,
6459}
6460
6461#[cfg(feature = "unstable_session_set_title")]
6462impl SessionTitleCapabilities {
6463    /// Builds an empty [`SessionTitleCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6464    #[must_use]
6465    pub fn new() -> Self {
6466        Self::default()
6467    }
6468
6469    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6470    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6471    /// these keys.
6472    ///
6473    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6474    #[must_use]
6475    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6476        self.meta = meta.into_option();
6477        self
6478    }
6479}
6480
6481/// Capabilities for the `session/resume` method.
6482///
6483/// Supplying `{}` means the agent supports resuming sessions.
6484#[serde_as]
6485#[skip_serializing_none]
6486#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6487#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6488#[non_exhaustive]
6489pub struct SessionResumeCapabilities {
6490    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6491    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6492    /// these keys.
6493    ///
6494    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6495    #[serde_as(deserialize_as = "DefaultOnError")]
6496    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6497    #[serde(default)]
6498    #[serde(rename = "_meta")]
6499    pub meta: Option<Meta>,
6500}
6501
6502impl SessionResumeCapabilities {
6503    /// Builds an empty [`SessionResumeCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6504    #[must_use]
6505    pub fn new() -> Self {
6506        Self::default()
6507    }
6508
6509    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6510    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6511    /// these keys.
6512    ///
6513    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6514    #[must_use]
6515    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6516        self.meta = meta.into_option();
6517        self
6518    }
6519}
6520
6521/// Capabilities for the `session/close` method.
6522///
6523/// Supplying `{}` means the agent supports closing sessions.
6524#[serde_as]
6525#[skip_serializing_none]
6526#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6527#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6528#[non_exhaustive]
6529pub struct SessionCloseCapabilities {
6530    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6531    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6532    /// these keys.
6533    ///
6534    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6535    #[serde_as(deserialize_as = "DefaultOnError")]
6536    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6537    #[serde(default)]
6538    #[serde(rename = "_meta")]
6539    pub meta: Option<Meta>,
6540}
6541
6542impl SessionCloseCapabilities {
6543    /// Builds an empty [`SessionCloseCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6544    #[must_use]
6545    pub fn new() -> Self {
6546        Self::default()
6547    }
6548
6549    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6550    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6551    /// these keys.
6552    ///
6553    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6554    #[must_use]
6555    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6556        self.meta = meta.into_option();
6557        self
6558    }
6559}
6560
6561/// Prompt capabilities supported by the agent in `session/prompt` requests.
6562///
6563/// Baseline agent functionality requires support for `text`
6564/// and `resource_link` content blocks in prompt requests.
6565///
6566/// Other variants must be explicitly opted in to.
6567/// Capabilities for different types of content in prompt requests.
6568///
6569/// Indicates which content types beyond the baseline (text and resource links)
6570/// the agent can process.
6571///
6572/// See protocol docs: [Prompt Capabilities](https://agentclientprotocol.com/protocol/v1/initialization#prompt-capabilities)
6573#[serde_as]
6574#[skip_serializing_none]
6575#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6576#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6577#[serde(rename_all = "camelCase")]
6578#[non_exhaustive]
6579pub struct PromptCapabilities {
6580    /// Agent supports `image` content blocks.
6581    #[serde_as(deserialize_as = "DefaultOnError")]
6582    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6583    #[serde(default)]
6584    pub image: bool,
6585    /// Agent supports `audio` content blocks.
6586    #[serde_as(deserialize_as = "DefaultOnError")]
6587    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6588    #[serde(default)]
6589    pub audio: bool,
6590    /// Agent supports embedded context in `session/prompt` requests.
6591    ///
6592    /// When enabled, the Client is allowed to include `resource` content blocks
6593    /// in prompt requests for pieces of context that are referenced in the message.
6594    #[serde_as(deserialize_as = "DefaultOnError")]
6595    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6596    #[serde(default)]
6597    pub embedded_context: bool,
6598    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6599    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6600    /// these keys.
6601    ///
6602    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6603    #[serde_as(deserialize_as = "DefaultOnError")]
6604    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6605    #[serde(default)]
6606    #[serde(rename = "_meta")]
6607    pub meta: Option<Meta>,
6608}
6609
6610impl PromptCapabilities {
6611    /// Builds an empty [`PromptCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6612    #[must_use]
6613    pub fn new() -> Self {
6614        Self::default()
6615    }
6616
6617    /// Agent supports `image` content blocks.
6618    #[must_use]
6619    pub fn image(mut self, image: bool) -> Self {
6620        self.image = image;
6621        self
6622    }
6623
6624    /// Agent supports `audio` content blocks.
6625    #[must_use]
6626    pub fn audio(mut self, audio: bool) -> Self {
6627        self.audio = audio;
6628        self
6629    }
6630
6631    /// Agent supports embedded context in `session/prompt` requests.
6632    ///
6633    /// When enabled, the Client is allowed to include `resource` content blocks
6634    /// in prompt requests for pieces of context that are referenced in the message.
6635    #[must_use]
6636    pub fn embedded_context(mut self, embedded_context: bool) -> Self {
6637        self.embedded_context = embedded_context;
6638        self
6639    }
6640
6641    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6642    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6643    /// these keys.
6644    ///
6645    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6646    #[must_use]
6647    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6648        self.meta = meta.into_option();
6649        self
6650    }
6651}
6652
6653/// MCP capabilities supported by the agent
6654#[serde_as]
6655#[skip_serializing_none]
6656#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6657#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6658#[serde(rename_all = "camelCase")]
6659#[non_exhaustive]
6660pub struct McpCapabilities {
6661    /// Agent supports `http` MCP servers.
6662    #[serde_as(deserialize_as = "DefaultOnError")]
6663    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6664    #[serde(default)]
6665    pub http: bool,
6666    /// Agent supports `sse` MCP servers.
6667    #[serde_as(deserialize_as = "DefaultOnError")]
6668    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6669    #[serde(default)]
6670    pub sse: bool,
6671    /// **UNSTABLE**
6672    ///
6673    /// This capability is not part of the spec yet, and may be removed or changed at any point.
6674    ///
6675    /// Agent supports `acp` MCP servers.
6676    #[cfg(feature = "unstable_mcp_over_acp")]
6677    #[serde_as(deserialize_as = "DefaultOnError")]
6678    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6679    #[serde(default)]
6680    pub acp: bool,
6681    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6682    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6683    /// these keys.
6684    ///
6685    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6686    #[serde_as(deserialize_as = "DefaultOnError")]
6687    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
6688    #[serde(default)]
6689    #[serde(rename = "_meta")]
6690    pub meta: Option<Meta>,
6691}
6692
6693impl McpCapabilities {
6694    /// Builds an empty [`McpCapabilities`]. Use builder methods to advertise supported sub-capabilities.
6695    #[must_use]
6696    pub fn new() -> Self {
6697        Self::default()
6698    }
6699
6700    /// Agent supports `http` MCP servers.
6701    #[must_use]
6702    pub fn http(mut self, http: bool) -> Self {
6703        self.http = http;
6704        self
6705    }
6706
6707    /// Agent supports `sse` MCP servers.
6708    #[must_use]
6709    pub fn sse(mut self, sse: bool) -> Self {
6710        self.sse = sse;
6711        self
6712    }
6713
6714    /// **UNSTABLE**
6715    ///
6716    /// This capability is not part of the spec yet, and may be removed or changed at any point.
6717    ///
6718    /// Agent supports `acp` MCP servers.
6719    #[cfg(feature = "unstable_mcp_over_acp")]
6720    #[must_use]
6721    pub fn acp(mut self, acp: bool) -> Self {
6722        self.acp = acp;
6723        self
6724    }
6725
6726    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
6727    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
6728    /// these keys.
6729    ///
6730    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
6731    #[must_use]
6732    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
6733        self.meta = meta.into_option();
6734        self
6735    }
6736}
6737
6738// Method schema
6739
6740/// Names of all methods that agents handle.
6741///
6742/// Provides a centralized definition of method names used in the protocol.
6743#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
6744#[non_exhaustive]
6745pub struct AgentMethodNames {
6746    /// Method for initializing the connection.
6747    pub initialize: &'static str,
6748    /// Method for authenticating with the agent.
6749    pub authenticate: &'static str,
6750    /// Method for listing configurable providers.
6751    #[cfg(feature = "unstable_llm_providers")]
6752    pub providers_list: &'static str,
6753    /// Method for setting provider configuration.
6754    #[cfg(feature = "unstable_llm_providers")]
6755    pub providers_set: &'static str,
6756    /// Method for disabling a provider.
6757    #[cfg(feature = "unstable_llm_providers")]
6758    pub providers_disable: &'static str,
6759    /// Method for creating a new session.
6760    pub session_new: &'static str,
6761    /// Method for loading an existing session.
6762    pub session_load: &'static str,
6763    /// Method for setting the mode for a session.
6764    pub session_set_mode: &'static str,
6765    /// Method for setting a configuration option for a session.
6766    pub session_set_config_option: &'static str,
6767    /// Method for sending a prompt to the agent.
6768    pub session_prompt: &'static str,
6769    /// Notification for cancelling operations.
6770    pub session_cancel: &'static str,
6771    /// Method for exchanging MCP-over-ACP messages.
6772    #[cfg(feature = "unstable_mcp_over_acp")]
6773    pub mcp_message: &'static str,
6774    /// Method for listing existing sessions.
6775    pub session_list: &'static str,
6776    /// Method for deleting an existing session.
6777    pub session_delete: &'static str,
6778    /// Method for forking an existing session.
6779    #[cfg(feature = "unstable_session_fork")]
6780    pub session_fork: &'static str,
6781    /// Method for archiving a session.
6782    #[cfg(feature = "unstable_session_archive")]
6783    pub session_archive: &'static str,
6784    /// Method for unarchiving a session.
6785    #[cfg(feature = "unstable_session_archive")]
6786    pub session_unarchive: &'static str,
6787    /// Method for checking the status of a session.
6788    #[cfg(feature = "unstable_session_status")]
6789    pub session_status: &'static str,
6790    /// Method for querying the config options a session would start with.
6791    #[cfg(feature = "unstable_session_options")]
6792    pub session_options: &'static str,
6793    /// Method for setting the title of a session.
6794    #[cfg(feature = "unstable_session_set_title")]
6795    pub session_set_title: &'static str,
6796    /// Method for resuming an existing session.
6797    pub session_resume: &'static str,
6798    /// Method for closing an active session.
6799    pub session_close: &'static str,
6800    /// Method for logging out of an authenticated session.
6801    pub logout: &'static str,
6802    /// Method for querying the agent's authentication state.
6803    #[cfg(feature = "unstable_auth_status")]
6804    pub auth_status: &'static str,
6805}
6806
6807/// Constant containing all agent method names.
6808pub const AGENT_METHOD_NAMES: AgentMethodNames = AgentMethodNames {
6809    initialize: INITIALIZE_METHOD_NAME,
6810    authenticate: AUTHENTICATE_METHOD_NAME,
6811    #[cfg(feature = "unstable_llm_providers")]
6812    providers_list: PROVIDERS_LIST_METHOD_NAME,
6813    #[cfg(feature = "unstable_llm_providers")]
6814    providers_set: PROVIDERS_SET_METHOD_NAME,
6815    #[cfg(feature = "unstable_llm_providers")]
6816    providers_disable: PROVIDERS_DISABLE_METHOD_NAME,
6817    session_new: SESSION_NEW_METHOD_NAME,
6818    session_load: SESSION_LOAD_METHOD_NAME,
6819    session_set_mode: SESSION_SET_MODE_METHOD_NAME,
6820    session_set_config_option: SESSION_SET_CONFIG_OPTION_METHOD_NAME,
6821    session_prompt: SESSION_PROMPT_METHOD_NAME,
6822    session_cancel: SESSION_CANCEL_METHOD_NAME,
6823    #[cfg(feature = "unstable_mcp_over_acp")]
6824    mcp_message: MCP_MESSAGE_METHOD_NAME,
6825    session_list: SESSION_LIST_METHOD_NAME,
6826    session_delete: SESSION_DELETE_METHOD_NAME,
6827    #[cfg(feature = "unstable_session_fork")]
6828    session_fork: SESSION_FORK_METHOD_NAME,
6829    #[cfg(feature = "unstable_session_archive")]
6830    session_archive: SESSION_ARCHIVE_METHOD_NAME,
6831    #[cfg(feature = "unstable_session_archive")]
6832    session_unarchive: SESSION_UNARCHIVE_METHOD_NAME,
6833    #[cfg(feature = "unstable_session_status")]
6834    session_status: SESSION_STATUS_METHOD_NAME,
6835    #[cfg(feature = "unstable_session_options")]
6836    session_options: SESSION_OPTIONS_METHOD_NAME,
6837    #[cfg(feature = "unstable_session_set_title")]
6838    session_set_title: SESSION_SET_TITLE_METHOD_NAME,
6839    session_resume: SESSION_RESUME_METHOD_NAME,
6840    session_close: SESSION_CLOSE_METHOD_NAME,
6841    logout: LOGOUT_METHOD_NAME,
6842    #[cfg(feature = "unstable_auth_status")]
6843    auth_status: AUTH_STATUS_METHOD_NAME,
6844};
6845
6846/// Method name for the initialize request.
6847pub(crate) const INITIALIZE_METHOD_NAME: &str = "initialize";
6848/// Method name for the authenticate request.
6849pub(crate) const AUTHENTICATE_METHOD_NAME: &str = "authenticate";
6850/// Method name for listing configurable providers.
6851#[cfg(feature = "unstable_llm_providers")]
6852pub(crate) const PROVIDERS_LIST_METHOD_NAME: &str = "providers/list";
6853/// Method name for setting provider configuration.
6854#[cfg(feature = "unstable_llm_providers")]
6855pub(crate) const PROVIDERS_SET_METHOD_NAME: &str = "providers/set";
6856/// Method name for disabling a provider.
6857#[cfg(feature = "unstable_llm_providers")]
6858pub(crate) const PROVIDERS_DISABLE_METHOD_NAME: &str = "providers/disable";
6859/// Method name for creating a new session.
6860pub(crate) const SESSION_NEW_METHOD_NAME: &str = "session/new";
6861/// Method name for loading an existing session.
6862pub(crate) const SESSION_LOAD_METHOD_NAME: &str = "session/load";
6863/// Method name for setting the mode for a session.
6864pub(crate) const SESSION_SET_MODE_METHOD_NAME: &str = "session/set_mode";
6865/// Method name for setting a configuration option for a session.
6866pub(crate) const SESSION_SET_CONFIG_OPTION_METHOD_NAME: &str = "session/set_config_option";
6867/// Method name for sending a prompt.
6868pub(crate) const SESSION_PROMPT_METHOD_NAME: &str = "session/prompt";
6869/// Method name for the cancel notification.
6870pub(crate) const SESSION_CANCEL_METHOD_NAME: &str = "session/cancel";
6871/// Method name for listing existing sessions.
6872pub(crate) const SESSION_LIST_METHOD_NAME: &str = "session/list";
6873/// Method name for deleting an existing session.
6874pub(crate) const SESSION_DELETE_METHOD_NAME: &str = "session/delete";
6875/// Method name for forking an existing session.
6876#[cfg(feature = "unstable_session_fork")]
6877pub(crate) const SESSION_FORK_METHOD_NAME: &str = "session/fork";
6878/// Method name for archiving a session.
6879#[cfg(feature = "unstable_session_archive")]
6880pub(crate) const SESSION_ARCHIVE_METHOD_NAME: &str = "session/archive";
6881/// Method name for unarchiving a session.
6882#[cfg(feature = "unstable_session_archive")]
6883pub(crate) const SESSION_UNARCHIVE_METHOD_NAME: &str = "session/unarchive";
6884/// Method name for checking the status of a session.
6885#[cfg(feature = "unstable_session_status")]
6886pub(crate) const SESSION_STATUS_METHOD_NAME: &str = "session/status";
6887/// Method name for querying the config options a session would start with.
6888#[cfg(feature = "unstable_session_options")]
6889pub(crate) const SESSION_OPTIONS_METHOD_NAME: &str = "session/options";
6890/// Method name for setting the title of a session.
6891#[cfg(feature = "unstable_session_set_title")]
6892pub(crate) const SESSION_SET_TITLE_METHOD_NAME: &str = "session/set_title";
6893/// Method name for resuming an existing session.
6894pub(crate) const SESSION_RESUME_METHOD_NAME: &str = "session/resume";
6895/// Method name for closing an active session.
6896pub(crate) const SESSION_CLOSE_METHOD_NAME: &str = "session/close";
6897/// Method name for logging out of an authenticated session.
6898pub(crate) const LOGOUT_METHOD_NAME: &str = "logout";
6899/// Method name for the `auth/status` request.
6900#[cfg(feature = "unstable_auth_status")]
6901pub(crate) const AUTH_STATUS_METHOD_NAME: &str = "auth/status";
6902
6903/// All possible requests that a client can send to an agent.
6904///
6905/// This enum is used internally for routing RPC requests. You typically won't need
6906/// to use this directly.
6907///
6908/// This enum encompasses all method calls from client to agent.
6909#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
6910#[derive(Clone, Debug, Serialize, Deserialize)]
6911#[serde(untagged)]
6912#[cfg_attr(feature = "schemars", schemars(inline))]
6913#[non_exhaustive]
6914#[allow(clippy::large_enum_variant)]
6915pub enum ClientRequest {
6916    /// Establishes the connection with a client and negotiates protocol capabilities.
6917    ///
6918    /// This method is called once at the beginning of the connection to:
6919    /// - Negotiate the protocol version to use
6920    /// - Exchange capability information between client and agent
6921    /// - Determine available authentication methods
6922    ///
6923    /// The agent should respond with its supported protocol version and capabilities.
6924    ///
6925    /// See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/v1/initialization)
6926    InitializeRequest(InitializeRequest),
6927    /// Authenticates the client using the specified authentication method.
6928    ///
6929    /// Called when the agent requires authentication before allowing session creation.
6930    /// The client provides an authentication method ID that was advertised during
6931    /// initialization and whose type defines the `authenticate` flow.
6932    ///
6933    /// After successful authentication, the client can proceed to create sessions with
6934    /// `session/new` without receiving an `auth_required` (`-32000`) error.
6935    ///
6936    /// See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/v1/initialization)
6937    AuthenticateRequest(AuthenticateRequest),
6938    /// **UNSTABLE**
6939    ///
6940    /// This capability is not part of the spec yet, and may be removed or changed at any point.
6941    ///
6942    /// Lists providers that can be configured by the client.
6943    #[cfg(feature = "unstable_llm_providers")]
6944    ListProvidersRequest(ListProvidersRequest),
6945    /// **UNSTABLE**
6946    ///
6947    /// This capability is not part of the spec yet, and may be removed or changed at any point.
6948    ///
6949    /// Replaces the configuration for a provider.
6950    #[cfg(feature = "unstable_llm_providers")]
6951    SetProviderRequest(SetProviderRequest),
6952    /// **UNSTABLE**
6953    ///
6954    /// This capability is not part of the spec yet, and may be removed or changed at any point.
6955    ///
6956    /// Disables a provider.
6957    #[cfg(feature = "unstable_llm_providers")]
6958    DisableProviderRequest(DisableProviderRequest),
6959    /// Logs out of the current authenticated state.
6960    ///
6961    /// After a successful logout, all new sessions will require authentication.
6962    /// There is no guarantee about the behavior of already running sessions.
6963    LogoutRequest(LogoutRequest),
6964    /// **UNSTABLE**
6965    ///
6966    /// This capability is not part of the spec yet, and may be removed or changed at any point.
6967    ///
6968    /// Queries the agent's current authentication state.
6969    ///
6970    /// This method is only available if the agent advertises the `auth.status` capability.
6971    /// It MUST NOT change any agent state, and agents MUST NOT reject it with `auth_required`.
6972    #[cfg(feature = "unstable_auth_status")]
6973    AuthStatusRequest(AuthStatusRequest),
6974    /// Creates a new conversation session with the agent.
6975    ///
6976    /// Sessions represent independent conversation contexts with their own history and state.
6977    ///
6978    /// The agent should:
6979    /// - Create a new session context
6980    /// - Connect to any specified MCP servers
6981    /// - Return a unique session ID for future requests
6982    ///
6983    /// May return an `auth_required` (`-32000`) error if the agent requires authentication.
6984    ///
6985    /// See protocol docs: [Session Setup](https://agentclientprotocol.com/protocol/v1/session-setup)
6986    NewSessionRequest(NewSessionRequest),
6987    /// Loads an existing session to resume a previous conversation.
6988    ///
6989    /// This method is only available if the agent advertises the `loadSession` capability.
6990    ///
6991    /// The agent should:
6992    /// - Restore the session context and conversation history
6993    /// - Connect to the specified MCP servers
6994    /// - Stream the entire conversation history back to the client via notifications
6995    ///
6996    /// See protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/v1/session-setup#loading-sessions)
6997    LoadSessionRequest(LoadSessionRequest),
6998    /// Lists existing sessions known to the agent.
6999    ///
7000    /// This method is only available if the agent advertises the `sessionCapabilities.list` capability.
7001    ///
7002    /// The agent should return metadata about sessions with optional filtering and pagination support.
7003    ListSessionsRequest(ListSessionsRequest),
7004    /// Deletes an existing session from `session/list`.
7005    ///
7006    /// This method is only available if the agent advertises the `sessionCapabilities.delete` capability.
7007    DeleteSessionRequest(DeleteSessionRequest),
7008    #[cfg(feature = "unstable_session_fork")]
7009    /// **UNSTABLE**
7010    ///
7011    /// This capability is not part of the spec yet, and may be removed or changed at any point.
7012    ///
7013    /// Forks an existing session to create a new independent session.
7014    ///
7015    /// This method is only available if the agent advertises the `session.fork` capability.
7016    ///
7017    /// The agent should create a new session with the same conversation context as the
7018    /// original, allowing operations like generating summaries without affecting the
7019    /// original session's history.
7020    ///
7021    /// As with `session/new`, the forked session is active once the agent responds,
7022    /// set up with the request's `cwd`, `additionalDirectories`, and `mcpServers`.
7023    /// The client can prompt it without calling `session/load` or `session/resume` first.
7024    ForkSessionRequest(ForkSessionRequest),
7025    #[cfg(feature = "unstable_session_archive")]
7026    /// **UNSTABLE**
7027    ///
7028    /// This capability is not part of the spec yet, and may be removed or changed at any point.
7029    ///
7030    /// Archives a session, hiding it from default `session/list` results.
7031    ///
7032    /// This method is only available if the agent advertises the `sessionCapabilities.archive` capability.
7033    ArchiveSessionRequest(ArchiveSessionRequest),
7034    #[cfg(feature = "unstable_session_archive")]
7035    /// **UNSTABLE**
7036    ///
7037    /// This capability is not part of the spec yet, and may be removed or changed at any point.
7038    ///
7039    /// Unarchives a session, returning it to default `session/list` results.
7040    ///
7041    /// This method is only available if the agent advertises the `sessionCapabilities.archive` capability.
7042    UnarchiveSessionRequest(UnarchiveSessionRequest),
7043    #[cfg(feature = "unstable_session_status")]
7044    /// **UNSTABLE**
7045    ///
7046    /// This capability is not part of the spec yet, and may be removed or changed at any point.
7047    ///
7048    /// Checks whether the Agent has a session in memory, without changing it.
7049    ///
7050    /// This method is only available if the agent advertises the `sessionCapabilities.status` capability.
7051    SessionStatusRequest(SessionStatusRequest),
7052    #[cfg(feature = "unstable_session_options")]
7053    /// **UNSTABLE**
7054    ///
7055    /// This capability is not part of the spec yet, and may be removed or changed at any point.
7056    ///
7057    /// Returns the config options a session would start with, without creating or resuming a session.
7058    ///
7059    /// This method is only available if the agent advertises the `sessionCapabilities.options` capability.
7060    SessionOptionsRequest(SessionOptionsRequest),
7061    #[cfg(feature = "unstable_session_set_title")]
7062    /// **UNSTABLE**
7063    ///
7064    /// This capability is not part of the spec yet, and may be removed or changed at any point.
7065    ///
7066    /// Sets the title of a session.
7067    ///
7068    /// This method is only available if the agent advertises the `sessionCapabilities.title` capability.
7069    ///
7070    /// The session does not need to be active on the connection. The agent stores the
7071    /// title and returns the stored title, which may be normalized.
7072    SetSessionTitleRequest(SetSessionTitleRequest),
7073    /// Resumes an existing session without returning previous messages.
7074    ///
7075    /// This method is only available if the agent advertises the `sessionCapabilities.resume` capability.
7076    ///
7077    /// The agent should resume the session context, allowing the conversation to continue
7078    /// without replaying the message history (unlike `session/load`).
7079    ResumeSessionRequest(ResumeSessionRequest),
7080    /// Closes an active session and frees up any resources associated with it.
7081    ///
7082    /// This method is only available if the agent advertises the `sessionCapabilities.close` capability.
7083    ///
7084    /// The agent MUST cancel any ongoing work (as if `session/cancel` was called)
7085    /// and then free up any resources associated with the session.
7086    CloseSessionRequest(CloseSessionRequest),
7087    /// Sets the current mode for a session.
7088    ///
7089    /// Allows switching between different agent modes (e.g., "ask", "architect", "code")
7090    /// that affect system prompts, tool availability, and permission behaviors.
7091    ///
7092    /// The mode MUST be one of the modes advertised in `availableModes` during session
7093    /// creation or loading. Agents may also change modes autonomously and notify the
7094    /// client via `current_mode_update` notifications.
7095    ///
7096    /// This method can be called at any time during a session, whether the Agent is
7097    /// idle or actively generating a response.
7098    ///
7099    /// See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/session-modes)
7100    SetSessionModeRequest(SetSessionModeRequest),
7101    /// Sets the current value for a session configuration option.
7102    SetSessionConfigOptionRequest(SetSessionConfigOptionRequest),
7103    /// Processes a user prompt within a session.
7104    ///
7105    /// This method handles the whole lifecycle of a prompt:
7106    /// - Receives user messages with optional context (files, images, etc.)
7107    /// - Processes the prompt using language models
7108    /// - Reports language model content and tool calls to the Clients
7109    /// - Requests permission to run tools
7110    /// - Executes any requested tool calls
7111    /// - Returns when the turn is complete with a stop reason
7112    ///
7113    /// See protocol docs: [Prompt Turn](https://agentclientprotocol.com/protocol/v1/prompt-turn)
7114    PromptRequest(PromptRequest),
7115    /// Handles extension method requests from the client.
7116    ///
7117    /// Extension methods provide a way to add custom functionality while maintaining
7118    /// protocol compatibility.
7119    ///
7120    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
7121    ExtMethodRequest(ExtRequest),
7122}
7123
7124impl_request_dispatch! {
7125    ClientRequest => AgentResponse {
7126        InitializeRequest => InitializeResponse: AGENT_METHOD_NAMES.initialize,
7127        AuthenticateRequest => AuthenticateResponse: AGENT_METHOD_NAMES.authenticate,
7128        #[cfg(feature = "unstable_llm_providers")]
7129        ListProvidersRequest => ListProvidersResponse: AGENT_METHOD_NAMES.providers_list,
7130        #[cfg(feature = "unstable_llm_providers")]
7131        SetProviderRequest => SetProviderResponse: AGENT_METHOD_NAMES.providers_set,
7132        #[cfg(feature = "unstable_llm_providers")]
7133        DisableProviderRequest => DisableProviderResponse: AGENT_METHOD_NAMES.providers_disable,
7134        LogoutRequest => LogoutResponse: AGENT_METHOD_NAMES.logout,
7135        #[cfg(feature = "unstable_auth_status")]
7136        AuthStatusRequest => AuthStatusResponse: AGENT_METHOD_NAMES.auth_status,
7137        NewSessionRequest => NewSessionResponse: AGENT_METHOD_NAMES.session_new,
7138        LoadSessionRequest => LoadSessionResponse: AGENT_METHOD_NAMES.session_load,
7139        ListSessionsRequest => ListSessionsResponse: AGENT_METHOD_NAMES.session_list,
7140        DeleteSessionRequest => DeleteSessionResponse: AGENT_METHOD_NAMES.session_delete,
7141        #[cfg(feature = "unstable_session_fork")]
7142        ForkSessionRequest => ForkSessionResponse: AGENT_METHOD_NAMES.session_fork,
7143        #[cfg(feature = "unstable_session_archive")]
7144        ArchiveSessionRequest => ArchiveSessionResponse: AGENT_METHOD_NAMES.session_archive,
7145        #[cfg(feature = "unstable_session_archive")]
7146        UnarchiveSessionRequest => UnarchiveSessionResponse: AGENT_METHOD_NAMES.session_unarchive,
7147        #[cfg(feature = "unstable_session_status")]
7148        SessionStatusRequest => SessionStatusResponse: AGENT_METHOD_NAMES.session_status,
7149        #[cfg(feature = "unstable_session_options")]
7150        SessionOptionsRequest => SessionOptionsResponse: AGENT_METHOD_NAMES.session_options,
7151        #[cfg(feature = "unstable_session_set_title")]
7152        SetSessionTitleRequest => SetSessionTitleResponse: AGENT_METHOD_NAMES.session_set_title,
7153        ResumeSessionRequest => ResumeSessionResponse: AGENT_METHOD_NAMES.session_resume,
7154        CloseSessionRequest => CloseSessionResponse: AGENT_METHOD_NAMES.session_close,
7155        SetSessionModeRequest => SetSessionModeResponse: AGENT_METHOD_NAMES.session_set_mode,
7156        SetSessionConfigOptionRequest => SetSessionConfigOptionResponse: AGENT_METHOD_NAMES.session_set_config_option,
7157        PromptRequest => PromptResponse: AGENT_METHOD_NAMES.session_prompt,
7158    }
7159    extension ExtMethodRequest(ExtRequest) => ExtMethodResponse;
7160}
7161
7162/// All possible responses that an agent can send to a client.
7163///
7164/// This enum is used internally for routing RPC responses. You typically won't need
7165/// to use this directly - the responses are handled automatically by the connection.
7166///
7167/// These are responses to the corresponding `ClientRequest` variants.
7168#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
7169#[derive(Clone, Debug, Serialize, Deserialize)]
7170#[serde(untagged)]
7171#[cfg_attr(feature = "schemars", schemars(inline))]
7172#[non_exhaustive]
7173#[allow(clippy::large_enum_variant)]
7174pub enum AgentResponse {
7175    /// Successful result returned for a `initialize` request.
7176    InitializeResponse(InitializeResponse),
7177    /// Successful result returned for a `authenticate` request.
7178    AuthenticateResponse(#[serde(default)] AuthenticateResponse),
7179    /// Successful result returned for a `providers/list` request.
7180    #[cfg(feature = "unstable_llm_providers")]
7181    ListProvidersResponse(ListProvidersResponse),
7182    /// Successful result returned for a `providers/set` request.
7183    #[cfg(feature = "unstable_llm_providers")]
7184    SetProviderResponse(#[serde(default)] SetProviderResponse),
7185    /// Successful result returned for a `providers/disable` request.
7186    #[cfg(feature = "unstable_llm_providers")]
7187    DisableProviderResponse(#[serde(default)] DisableProviderResponse),
7188    /// Successful result returned for a `logout` request.
7189    LogoutResponse(#[serde(default)] LogoutResponse),
7190    /// Successful result returned for an `auth/status` request.
7191    #[cfg(feature = "unstable_auth_status")]
7192    AuthStatusResponse(AuthStatusResponse),
7193    /// Successful result returned for a `session/new` request.
7194    NewSessionResponse(NewSessionResponse),
7195    /// Successful result returned for a `session/load` request.
7196    LoadSessionResponse(#[serde(default)] LoadSessionResponse),
7197    /// Successful result returned for a `session/list` request.
7198    ListSessionsResponse(ListSessionsResponse),
7199    /// Successful result returned for a `session/delete` request.
7200    DeleteSessionResponse(#[serde(default)] DeleteSessionResponse),
7201    /// Successful result returned for a `session/fork` request.
7202    #[cfg(feature = "unstable_session_fork")]
7203    ForkSessionResponse(ForkSessionResponse),
7204    /// Successful result returned for a `session/archive` request.
7205    #[cfg(feature = "unstable_session_archive")]
7206    ArchiveSessionResponse(#[serde(default)] ArchiveSessionResponse),
7207    /// Successful result returned for a `session/unarchive` request.
7208    #[cfg(feature = "unstable_session_archive")]
7209    UnarchiveSessionResponse(#[serde(default)] UnarchiveSessionResponse),
7210    /// Successful result returned for a `session/status` request.
7211    #[cfg(feature = "unstable_session_status")]
7212    SessionStatusResponse(SessionStatusResponse),
7213    /// Successful result returned for a `session/options` request.
7214    #[cfg(feature = "unstable_session_options")]
7215    SessionOptionsResponse(#[serde(default)] SessionOptionsResponse),
7216    /// Successful result returned for a `session/set_title` request.
7217    #[cfg(feature = "unstable_session_set_title")]
7218    SetSessionTitleResponse(SetSessionTitleResponse),
7219    /// Successful result returned for a `session/resume` request.
7220    ResumeSessionResponse(#[serde(default)] ResumeSessionResponse),
7221    /// Successful result returned for a `session/close` request.
7222    CloseSessionResponse(#[serde(default)] CloseSessionResponse),
7223    /// Successful result returned for a `session/set_mode` request.
7224    SetSessionModeResponse(#[serde(default)] SetSessionModeResponse),
7225    /// Successful result returned for a `session/set_config_option` request.
7226    SetSessionConfigOptionResponse(SetSessionConfigOptionResponse),
7227    /// Successful result returned for a `session/prompt` request.
7228    PromptResponse(PromptResponse),
7229    /// Successful result returned by an extension method outside the core ACP method set.
7230    ExtMethodResponse(ExtResponse),
7231}
7232
7233/// All possible notifications that a client can send to an agent.
7234///
7235/// This enum is used internally for routing RPC notifications. You typically won't need
7236/// to use this directly.
7237///
7238/// Notifications do not expect a response.
7239#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
7240#[derive(Clone, Debug, Serialize, Deserialize)]
7241#[serde(untagged)]
7242#[cfg_attr(feature = "schemars", schemars(inline))]
7243#[non_exhaustive]
7244#[allow(clippy::large_enum_variant)]
7245pub enum ClientNotification {
7246    /// Cancels ongoing operations for a session.
7247    ///
7248    /// This is a notification sent by the client to cancel an ongoing prompt turn.
7249    ///
7250    /// Upon receiving this notification, the Agent SHOULD:
7251    /// - Stop all language model requests as soon as possible
7252    /// - Abort all tool call invocations in progress
7253    /// - Send any pending `session/update` notifications
7254    /// - Respond to the original `session/prompt` request with the `cancelled` stop reason
7255    ///
7256    /// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v1/prompt-turn#cancellation)
7257    CancelNotification(CancelNotification),
7258    /// **UNSTABLE**
7259    ///
7260    /// This capability is not part of the spec yet, and may be removed or changed at any point.
7261    ///
7262    /// Sends an MCP-over-ACP notification.
7263    #[cfg(feature = "unstable_mcp_over_acp")]
7264    MessageMcpNotification(MessageMcpNotification),
7265    /// Handles extension notifications from the client.
7266    ///
7267    /// Extension notifications provide a way to send one-way messages for custom functionality
7268    /// while maintaining protocol compatibility.
7269    ///
7270    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
7271    ExtNotification(ExtNotification),
7272}
7273
7274impl_message_dispatch! {
7275    ClientNotification {
7276        CancelNotification => AGENT_METHOD_NAMES.session_cancel,
7277        #[cfg(feature = "unstable_mcp_over_acp")]
7278        MessageMcpNotification => AGENT_METHOD_NAMES.mcp_message,
7279    }
7280    extension ExtNotification(ExtNotification);
7281}
7282
7283/// Notification to cancel ongoing operations for a session.
7284///
7285/// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v1/prompt-turn#cancellation)
7286#[serde_as]
7287#[skip_serializing_none]
7288#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
7289#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
7290#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_CANCEL_METHOD_NAME)))]
7291#[serde(rename_all = "camelCase")]
7292#[non_exhaustive]
7293pub struct CancelNotification {
7294    /// The ID of the session to cancel operations for.
7295    pub session_id: SessionId,
7296    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
7297    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
7298    /// these keys.
7299    ///
7300    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
7301    #[serde_as(deserialize_as = "DefaultOnError")]
7302    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
7303    #[serde(default)]
7304    #[serde(rename = "_meta")]
7305    pub meta: Option<Meta>,
7306}
7307
7308impl CancelNotification {
7309    /// Builds [`CancelNotification`] with the required notification fields set. Optional fields start unset or empty.
7310    #[must_use]
7311    pub fn new(session_id: impl Into<SessionId>) -> Self {
7312        Self {
7313            session_id: session_id.into(),
7314            meta: None,
7315        }
7316    }
7317
7318    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
7319    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
7320    /// these keys.
7321    ///
7322    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility)
7323    #[must_use]
7324    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
7325        self.meta = meta.into_option();
7326        self
7327    }
7328}
7329
7330#[cfg(test)]
7331mod test_serialization {
7332    use super::*;
7333    use serde_json::json;
7334
7335    fn test_meta() -> Meta {
7336        json!({ "source": "test" }).as_object().unwrap().clone()
7337    }
7338
7339    fn serialized_meta_key_count(value: &impl serde::Serialize) -> usize {
7340        serde_json::to_string(value)
7341            .unwrap()
7342            .matches("\"_meta\"")
7343            .count()
7344    }
7345
7346    /// v1 reports prompt failures as JSON-RPC errors. Only the subagent
7347    /// snapshot has an `error` stop reason, because a child has no prompt response.
7348    #[test]
7349    fn prompt_response_has_no_error_stop_reason() {
7350        assert_eq!(
7351            serde_json::from_value::<PromptResponse>(json!({ "stopReason": "end_turn" }))
7352                .unwrap()
7353                .stop_reason,
7354            StopReason::EndTurn
7355        );
7356        assert!(
7357            serde_json::from_value::<PromptResponse>(json!({ "stopReason": "error" })).is_err()
7358        );
7359    }
7360
7361    #[test]
7362    fn test_initialize_capabilities_default_on_malformed_values() {
7363        let request: InitializeRequest = serde_json::from_value(json!({
7364            "protocolVersion": 1,
7365            "clientCapabilities": false
7366        }))
7367        .unwrap();
7368        assert_eq!(request.client_capabilities, ClientCapabilities::default());
7369
7370        let response: InitializeResponse = serde_json::from_value(json!({
7371            "protocolVersion": 1,
7372            "agentCapabilities": false
7373        }))
7374        .unwrap();
7375        assert_eq!(response.agent_capabilities, AgentCapabilities::default());
7376    }
7377
7378    #[test]
7379    fn test_agent_capabilities_default_on_malformed_values() {
7380        let capabilities: AgentCapabilities = serde_json::from_value(json!({
7381            "loadSession": "yes",
7382            "promptCapabilities": {
7383                "image": "yes",
7384                "audio": true,
7385                "embeddedContext": {}
7386            },
7387            "mcpCapabilities": {
7388                "http": "yes",
7389                "sse": true
7390            },
7391            "sessionCapabilities": false,
7392            "auth": false
7393        }))
7394        .unwrap();
7395
7396        assert!(!capabilities.load_session);
7397        assert!(!capabilities.prompt_capabilities.image);
7398        assert!(capabilities.prompt_capabilities.audio);
7399        assert!(!capabilities.prompt_capabilities.embedded_context);
7400        assert!(!capabilities.mcp_capabilities.http);
7401        assert!(capabilities.mcp_capabilities.sse);
7402        assert_eq!(
7403            capabilities.session_capabilities,
7404            SessionCapabilities::default()
7405        );
7406        assert_eq!(capabilities.auth, AgentAuthCapabilities::default());
7407    }
7408
7409    #[test]
7410    fn test_mcp_server_stdio_serialization() {
7411        let server = McpServer::Stdio(
7412            McpServerStdio::new("test-server", "/usr/bin/server")
7413                .args(vec!["--port".to_string(), "3000".to_string()])
7414                .env(vec![EnvVariable::new("API_KEY", "secret123")]),
7415        );
7416
7417        let json = serde_json::to_value(&server).unwrap();
7418        assert_eq!(
7419            json,
7420            json!({
7421                "name": "test-server",
7422                "command": "/usr/bin/server",
7423                "args": ["--port", "3000"],
7424                "env": [
7425                    {
7426                        "name": "API_KEY",
7427                        "value": "secret123"
7428                    }
7429                ]
7430            })
7431        );
7432
7433        let deserialized: McpServer = serde_json::from_value(json).unwrap();
7434        match deserialized {
7435            McpServer::Stdio(McpServerStdio {
7436                name,
7437                command,
7438                args,
7439                env,
7440                meta: _,
7441            }) => {
7442                assert_eq!(name, "test-server");
7443                assert_eq!(command, PathBuf::from("/usr/bin/server"));
7444                assert_eq!(args, vec!["--port", "3000"]);
7445                assert_eq!(env.len(), 1);
7446                assert_eq!(env[0].name, "API_KEY");
7447                assert_eq!(env[0].value, "secret123");
7448            }
7449            _ => panic!("Expected Stdio variant"),
7450        }
7451    }
7452
7453    #[test]
7454    fn test_mcp_server_http_serialization() {
7455        let server = McpServer::Http(
7456            McpServerHttp::new("http-server", "https://api.example.com").headers(vec![
7457                HttpHeader::new("Authorization", "Bearer token123"),
7458                HttpHeader::new("Content-Type", "application/json"),
7459            ]),
7460        );
7461
7462        let json = serde_json::to_value(&server).unwrap();
7463        assert_eq!(
7464            json,
7465            json!({
7466                "type": "http",
7467                "name": "http-server",
7468                "url": "https://api.example.com",
7469                "headers": [
7470                    {
7471                        "name": "Authorization",
7472                        "value": "Bearer token123"
7473                    },
7474                    {
7475                        "name": "Content-Type",
7476                        "value": "application/json"
7477                    }
7478                ]
7479            })
7480        );
7481
7482        let deserialized: McpServer = serde_json::from_value(json).unwrap();
7483        match deserialized {
7484            McpServer::Http(McpServerHttp {
7485                name,
7486                url,
7487                headers,
7488                meta: _,
7489            }) => {
7490                assert_eq!(name, "http-server");
7491                assert_eq!(url, "https://api.example.com");
7492                assert_eq!(headers.len(), 2);
7493                assert_eq!(headers[0].name, "Authorization");
7494                assert_eq!(headers[0].value, "Bearer token123");
7495                assert_eq!(headers[1].name, "Content-Type");
7496                assert_eq!(headers[1].value, "application/json");
7497            }
7498            _ => panic!("Expected Http variant"),
7499        }
7500    }
7501
7502    #[cfg(feature = "unstable_mcp_over_acp")]
7503    #[test]
7504    fn test_mcp_server_acp_serialization() {
7505        let server = McpServer::Acp(McpServerAcp::new("project-tools", "project-tools-id"));
7506
7507        let json = serde_json::to_value(&server).unwrap();
7508        assert_eq!(
7509            json,
7510            json!({
7511                "type": "acp",
7512                "name": "project-tools",
7513                "serverId": "project-tools-id"
7514            })
7515        );
7516
7517        let deserialized: McpServer = serde_json::from_value(json).unwrap();
7518        match deserialized {
7519            McpServer::Acp(McpServerAcp {
7520                name,
7521                server_id: id,
7522                meta: _,
7523            }) => {
7524                assert_eq!(name, "project-tools");
7525                assert_eq!(id, McpServerAcpId::new("project-tools-id"));
7526            }
7527            _ => panic!("Expected Acp variant"),
7528        }
7529    }
7530
7531    #[cfg(feature = "unstable_mcp_over_acp")]
7532    #[test]
7533    fn test_client_mcp_message_method_names() {
7534        use serde_json::json;
7535
7536        assert_eq!(AGENT_METHOD_NAMES.mcp_message, "mcp/message");
7537
7538        let notification =
7539            MessageMcpNotification::new("server-1", "req-1", "notifications/progress");
7540        assert_eq!(
7541            ClientNotification::MessageMcpNotification(notification.clone()).method(),
7542            "mcp/message"
7543        );
7544        assert_eq!(
7545            serde_json::to_value(notification).unwrap(),
7546            json!({
7547                "serverId": "server-1",
7548                "requestId": "req-1",
7549                "method": "notifications/progress"
7550            })
7551        );
7552        let notification: MessageMcpNotification = serde_json::from_value(json!({
7553            "serverId": "server-1", "requestId": "req-1", "method": "notifications/progress",
7554            "params": null, "_meta": null
7555        }))
7556        .unwrap();
7557        assert_eq!(notification.params, None);
7558        assert_eq!(notification.meta, None);
7559        for key in ["serverId", "requestId", "method"] {
7560            let mut value = json!({"serverId":"server-1", "requestId":"req-1", "method":"notifications/progress"});
7561            value.as_object_mut().unwrap().remove(key);
7562            assert!(serde_json::from_value::<MessageMcpNotification>(value).is_err());
7563        }
7564    }
7565
7566    #[cfg(all(feature = "unstable_mcp_over_acp", feature = "schemars"))]
7567    #[test]
7568    fn test_mcp_server_acp_schema() {
7569        let mcp_server_schema = serde_json::to_value(schemars::schema_for!(McpServer)).unwrap();
7570        assert!(json_contains_entry(
7571            &mcp_server_schema,
7572            "const",
7573            &json!("acp")
7574        ));
7575        assert!(json_contains_entry(
7576            &mcp_server_schema,
7577            "$ref",
7578            &json!("#/$defs/McpServerAcp")
7579        ));
7580
7581        let capabilities_schema =
7582            serde_json::to_value(schemars::schema_for!(McpCapabilities)).unwrap();
7583        assert!(json_contains_key(&capabilities_schema, "acp"));
7584    }
7585
7586    #[cfg(all(feature = "unstable_mcp_over_acp", feature = "schemars"))]
7587    fn json_contains_entry(
7588        value: &serde_json::Value,
7589        key: &str,
7590        expected: &serde_json::Value,
7591    ) -> bool {
7592        match value {
7593            serde_json::Value::Object(map) => {
7594                map.get(key) == Some(expected)
7595                    || map
7596                        .values()
7597                        .any(|value| json_contains_entry(value, key, expected))
7598            }
7599            serde_json::Value::Array(values) => values
7600                .iter()
7601                .any(|value| json_contains_entry(value, key, expected)),
7602            _ => false,
7603        }
7604    }
7605
7606    #[cfg(all(feature = "unstable_mcp_over_acp", feature = "schemars"))]
7607    fn json_contains_key(value: &serde_json::Value, key: &str) -> bool {
7608        match value {
7609            serde_json::Value::Object(map) => {
7610                map.contains_key(key) || map.values().any(|value| json_contains_key(value, key))
7611            }
7612            serde_json::Value::Array(values) => {
7613                values.iter().any(|value| json_contains_key(value, key))
7614            }
7615            _ => false,
7616        }
7617    }
7618
7619    #[test]
7620    fn test_mcp_server_sse_serialization() {
7621        let server = McpServer::Sse(
7622            McpServerSse::new("sse-server", "https://sse.example.com/events")
7623                .headers(vec![HttpHeader::new("X-API-Key", "apikey456")]),
7624        );
7625
7626        let json = serde_json::to_value(&server).unwrap();
7627        assert_eq!(
7628            json,
7629            json!({
7630                "type": "sse",
7631                "name": "sse-server",
7632                "url": "https://sse.example.com/events",
7633                "headers": [
7634                    {
7635                        "name": "X-API-Key",
7636                        "value": "apikey456"
7637                    }
7638                ]
7639            })
7640        );
7641
7642        let deserialized: McpServer = serde_json::from_value(json).unwrap();
7643        match deserialized {
7644            McpServer::Sse(McpServerSse {
7645                name,
7646                url,
7647                headers,
7648                meta: _,
7649            }) => {
7650                assert_eq!(name, "sse-server");
7651                assert_eq!(url, "https://sse.example.com/events");
7652                assert_eq!(headers.len(), 1);
7653                assert_eq!(headers[0].name, "X-API-Key");
7654                assert_eq!(headers[0].value, "apikey456");
7655            }
7656            _ => panic!("Expected Sse variant"),
7657        }
7658    }
7659
7660    #[test]
7661    fn test_session_config_option_category_known_variants() {
7662        // Test serialization of known variants
7663        assert_eq!(
7664            serde_json::to_value(&SessionConfigOptionCategory::Mode).unwrap(),
7665            json!("mode")
7666        );
7667        assert_eq!(
7668            serde_json::to_value(&SessionConfigOptionCategory::Model).unwrap(),
7669            json!("model")
7670        );
7671        assert_eq!(
7672            serde_json::to_value(&SessionConfigOptionCategory::ModelConfig).unwrap(),
7673            json!("model_config")
7674        );
7675        #[cfg(feature = "unstable_speed_config_category")]
7676        assert_eq!(
7677            serde_json::to_value(&SessionConfigOptionCategory::Speed).unwrap(),
7678            json!("speed")
7679        );
7680        assert_eq!(
7681            serde_json::to_value(&SessionConfigOptionCategory::ThoughtLevel).unwrap(),
7682            json!("thought_level")
7683        );
7684
7685        // Test deserialization of known variants
7686        assert_eq!(
7687            serde_json::from_str::<SessionConfigOptionCategory>("\"mode\"").unwrap(),
7688            SessionConfigOptionCategory::Mode
7689        );
7690        assert_eq!(
7691            serde_json::from_str::<SessionConfigOptionCategory>("\"model\"").unwrap(),
7692            SessionConfigOptionCategory::Model
7693        );
7694        assert_eq!(
7695            serde_json::from_str::<SessionConfigOptionCategory>("\"model_config\"").unwrap(),
7696            SessionConfigOptionCategory::ModelConfig
7697        );
7698        #[cfg(feature = "unstable_speed_config_category")]
7699        assert_eq!(
7700            serde_json::from_str::<SessionConfigOptionCategory>("\"speed\"").unwrap(),
7701            SessionConfigOptionCategory::Speed
7702        );
7703        assert_eq!(
7704            serde_json::from_str::<SessionConfigOptionCategory>("\"thought_level\"").unwrap(),
7705            SessionConfigOptionCategory::ThoughtLevel
7706        );
7707    }
7708
7709    #[test]
7710    fn test_session_config_option_category_unknown_variants() {
7711        // Test that unknown strings are captured in Other variant
7712        let unknown: SessionConfigOptionCategory =
7713            serde_json::from_str("\"some_future_category\"").unwrap();
7714        assert_eq!(
7715            unknown,
7716            SessionConfigOptionCategory::Other("some_future_category".to_string())
7717        );
7718
7719        // Test round-trip of unknown category
7720        let json = serde_json::to_value(&unknown).unwrap();
7721        assert_eq!(json, json!("some_future_category"));
7722    }
7723
7724    #[cfg(not(feature = "unstable_speed_config_category"))]
7725    #[test]
7726    fn test_session_config_option_speed_is_unknown_without_feature() {
7727        let unknown: SessionConfigOptionCategory = serde_json::from_str("\"speed\"").unwrap();
7728        assert_eq!(
7729            unknown,
7730            SessionConfigOptionCategory::Other("speed".to_string())
7731        );
7732    }
7733
7734    #[test]
7735    fn test_session_config_option_category_custom_categories() {
7736        // Category names beginning with `_` are free for custom use
7737        let custom: SessionConfigOptionCategory =
7738            serde_json::from_str("\"_my_custom_category\"").unwrap();
7739        assert_eq!(
7740            custom,
7741            SessionConfigOptionCategory::Other("_my_custom_category".to_string())
7742        );
7743
7744        // Test round-trip preserves the custom category name
7745        let json = serde_json::to_value(&custom).unwrap();
7746        assert_eq!(json, json!("_my_custom_category"));
7747
7748        // Deserialize back and verify
7749        let deserialized: SessionConfigOptionCategory = serde_json::from_value(json).unwrap();
7750        assert_eq!(
7751            deserialized,
7752            SessionConfigOptionCategory::Other("_my_custom_category".to_string()),
7753        );
7754    }
7755
7756    #[test]
7757    fn test_auth_method_agent_serialization() {
7758        let method = AuthMethod::Agent(AuthMethodAgent::new("default-auth", "Default Auth"));
7759
7760        let json = serde_json::to_value(&method).unwrap();
7761        assert_eq!(
7762            json,
7763            json!({
7764                "id": "default-auth",
7765                "name": "Default Auth"
7766            })
7767        );
7768        // description should be omitted when None
7769        assert!(!json.as_object().unwrap().contains_key("description"));
7770        // Agent variant should not emit a `type` field (backward compat)
7771        assert!(!json.as_object().unwrap().contains_key("type"));
7772
7773        let deserialized: AuthMethod = serde_json::from_value(json).unwrap();
7774        match deserialized {
7775            AuthMethod::Agent(AuthMethodAgent { id, name, .. }) => {
7776                assert_eq!(id.0.as_ref(), "default-auth");
7777                assert_eq!(name, "Default Auth");
7778            }
7779            _ => panic!("Expected Agent variant"),
7780        }
7781    }
7782
7783    #[test]
7784    fn test_auth_method_explicit_agent_deserialization() {
7785        // An explicit `"type": "agent"` should also deserialize to Agent
7786        let json = json!({
7787            "id": "agent-auth",
7788            "name": "Agent Auth",
7789            "type": "agent"
7790        });
7791
7792        let deserialized: AuthMethod = serde_json::from_value(json).unwrap();
7793        assert!(matches!(deserialized, AuthMethod::Agent(_)));
7794    }
7795
7796    #[test]
7797    fn test_session_delete_serialization() {
7798        assert_eq!(AGENT_METHOD_NAMES.session_delete, "session/delete");
7799        assert_eq!(
7800            ClientRequest::DeleteSessionRequest(DeleteSessionRequest::new("sess_abc123")).method(),
7801            "session/delete"
7802        );
7803        assert_eq!(
7804            serde_json::to_value(DeleteSessionRequest::new("sess_abc123")).unwrap(),
7805            json!({
7806                "sessionId": "sess_abc123"
7807            })
7808        );
7809        assert_eq!(
7810            serde_json::to_value(DeleteSessionResponse::new()).unwrap(),
7811            json!({})
7812        );
7813        assert_eq!(
7814            serde_json::to_value(
7815                SessionCapabilities::new().delete(SessionDeleteCapabilities::new())
7816            )
7817            .unwrap(),
7818            json!({
7819                "delete": {}
7820            })
7821        );
7822    }
7823    #[cfg(feature = "unstable_session_set_title")]
7824    #[test]
7825    fn test_session_set_title_serialization() {
7826        assert_eq!(AGENT_METHOD_NAMES.session_set_title, "session/set_title");
7827        assert_eq!(
7828            ClientRequest::SetSessionTitleRequest(SetSessionTitleRequest::new(
7829                "sess_abc123",
7830                "Investigate OAuth timeout"
7831            ))
7832            .method(),
7833            "session/set_title"
7834        );
7835        assert_eq!(
7836            serde_json::to_value(SetSessionTitleRequest::new(
7837                "sess_abc123",
7838                "Investigate OAuth timeout"
7839            ))
7840            .unwrap(),
7841            json!({
7842                "sessionId": "sess_abc123",
7843                "title": "Investigate OAuth timeout"
7844            })
7845        );
7846        assert_eq!(
7847            serde_json::to_value(SetSessionTitleResponse::new("Investigate OAuth timeout"))
7848                .unwrap(),
7849            json!({
7850                "title": "Investigate OAuth timeout"
7851            })
7852        );
7853        assert_eq!(
7854            serde_json::to_value(SessionCapabilities::new().title(SessionTitleCapabilities::new()))
7855                .unwrap(),
7856            json!({
7857                "title": {}
7858            })
7859        );
7860    }
7861
7862    #[cfg(feature = "unstable_session_set_title")]
7863    #[test]
7864    fn test_session_set_title_requires_title() {
7865        for params in [
7866            json!({"sessionId": "sess_abc123"}),
7867            json!({"sessionId": "sess_abc123", "title": null}),
7868            json!({"sessionId": "sess_abc123", "title": 42}),
7869        ] {
7870            assert!(serde_json::from_value::<SetSessionTitleRequest>(params).is_err());
7871        }
7872        for result in [json!({}), json!({"title": null})] {
7873            assert!(serde_json::from_value::<SetSessionTitleResponse>(result).is_err());
7874        }
7875    }
7876
7877    #[cfg(feature = "unstable_session_options")]
7878    #[test]
7879    fn test_session_options_serialization() {
7880        assert_eq!(AGENT_METHOD_NAMES.session_options, "session/options");
7881        assert_eq!(
7882            ClientRequest::SessionOptionsRequest(SessionOptionsRequest::new("/home/user/project"))
7883                .method(),
7884            "session/options"
7885        );
7886        assert_eq!(
7887            serde_json::to_value(
7888                SessionOptionsRequest::new("/home/user/project")
7889                    .session_id(SessionId::new("sess_abc123"))
7890            )
7891            .unwrap(),
7892            json!({"cwd": "/home/user/project", "sessionId": "sess_abc123"})
7893        );
7894        assert_eq!(
7895            serde_json::from_value::<SessionOptionsRequest>(
7896                json!({"cwd": "/home/user/project", "additionalDirectories": null, "sessionId": null})
7897            )
7898            .unwrap(),
7899            SessionOptionsRequest::new("/home/user/project")
7900        );
7901        let request = NewSessionRequest::new("/home/user/project").config_options(vec![
7902            InitialSessionConfigOption::new("model", SessionConfigOptionValue::value_id("model-2")),
7903            InitialSessionConfigOption::new("fast", SessionConfigOptionValue::boolean(true)),
7904        ]);
7905        let value = serde_json::to_value(&request).unwrap();
7906        assert_eq!(
7907            value["configOptions"],
7908            json!([
7909                {"configId": "model", "value": "model-2"},
7910                {"configId": "fast", "type": "boolean", "value": true}
7911            ])
7912        );
7913        assert_eq!(
7914            serde_json::from_value::<NewSessionRequest>(value).unwrap(),
7915            request
7916        );
7917        assert!(
7918            serde_json::from_value::<NewSessionRequest>(json!({
7919                "cwd": "/home/user/project",
7920                "mcpServers": [],
7921                "configOptions": [{"type": "boolean", "value": true}]
7922            }))
7923            .is_err()
7924        );
7925        assert_eq!(
7926            serde_json::to_value(SessionOptionsResponse::new()).unwrap(),
7927            json!({})
7928        );
7929        #[cfg(feature = "unstable_session_fork")]
7930        {
7931            let fork =
7932                ForkSessionRequest::new("sess_abc123", "/home/user/project").config_options(vec![
7933                    InitialSessionConfigOption::new(
7934                        "model",
7935                        SessionConfigOptionValue::value_id("model-2"),
7936                    ),
7937                ]);
7938            let value = serde_json::to_value(&fork).unwrap();
7939            assert_eq!(
7940                value["configOptions"],
7941                json!([{"configId": "model", "value": "model-2"}])
7942            );
7943            assert_eq!(
7944                serde_json::from_value::<ForkSessionRequest>(value).unwrap(),
7945                fork
7946            );
7947            // `null` is an empty list, and a malformed entry fails the request.
7948            assert_eq!(
7949                serde_json::from_value::<ForkSessionRequest>(json!({
7950                    "sessionId": "sess_abc123",
7951                    "cwd": "/home/user/project",
7952                    "configOptions": null
7953                }))
7954                .unwrap(),
7955                ForkSessionRequest::new("sess_abc123", "/home/user/project")
7956            );
7957            assert!(
7958                serde_json::from_value::<ForkSessionRequest>(json!({
7959                    "sessionId": "sess_abc123",
7960                    "cwd": "/home/user/project",
7961                    "configOptions": [{"type": "boolean", "value": true}]
7962                }))
7963                .is_err()
7964            );
7965        }
7966        assert_eq!(
7967            serde_json::to_value(
7968                SessionCapabilities::new().options(SessionOptionsCapabilities::new())
7969            )
7970            .unwrap(),
7971            json!({"options": {}})
7972        );
7973    }
7974
7975    #[cfg(feature = "unstable_session_status")]
7976    #[test]
7977    fn test_session_status_serialization() {
7978        assert_eq!(AGENT_METHOD_NAMES.session_status, "session/status");
7979        assert_eq!(
7980            ClientRequest::SessionStatusRequest(SessionStatusRequest::new("sess_abc123")).method(),
7981            "session/status"
7982        );
7983        assert_eq!(
7984            serde_json::to_value(SessionStatusRequest::new("sess_abc123")).unwrap(),
7985            json!({"sessionId": "sess_abc123"})
7986        );
7987        assert_eq!(
7988            serde_json::to_value(SessionStatusResponse::new(SessionStatus::Saved)).unwrap(),
7989            json!({"status": "saved"})
7990        );
7991        assert_eq!(
7992            serde_json::to_value(
7993                SessionCapabilities::new().status(SessionStatusCapabilities::new())
7994            )
7995            .unwrap(),
7996            json!({"status": {}})
7997        );
7998    }
7999
8000    #[cfg(feature = "unstable_session_status")]
8001    #[test]
8002    fn test_session_status_is_strict_and_open() {
8003        let custom =
8004            serde_json::from_value::<SessionStatusResponse>(json!({"status": "_suspended"}))
8005                .unwrap();
8006        assert_eq!(
8007            custom.status,
8008            SessionStatus::Other("_suspended".to_string())
8009        );
8010        assert_eq!(
8011            serde_json::to_value(&custom).unwrap(),
8012            json!({"status": "_suspended"})
8013        );
8014        for result in [json!({}), json!({"status": null}), json!({"status": 1})] {
8015            assert!(serde_json::from_value::<SessionStatusResponse>(result).is_err());
8016        }
8017        for params in [json!({}), json!({"sessionId": null})] {
8018            assert!(serde_json::from_value::<SessionStatusRequest>(params).is_err());
8019        }
8020    }
8021
8022    #[cfg(feature = "unstable_session_archive")]
8023    #[test]
8024    fn test_session_archive_serialization() {
8025        assert_eq!(AGENT_METHOD_NAMES.session_archive, "session/archive");
8026        assert_eq!(AGENT_METHOD_NAMES.session_unarchive, "session/unarchive");
8027        assert_eq!(
8028            ClientRequest::ArchiveSessionRequest(ArchiveSessionRequest::new("sess_abc123"))
8029                .method(),
8030            "session/archive"
8031        );
8032        assert_eq!(
8033            ClientRequest::UnarchiveSessionRequest(UnarchiveSessionRequest::new("sess_abc123"))
8034                .method(),
8035            "session/unarchive"
8036        );
8037        assert_eq!(
8038            serde_json::to_value(ArchiveSessionRequest::new("sess_abc123")).unwrap(),
8039            json!({"sessionId": "sess_abc123"})
8040        );
8041        assert_eq!(
8042            serde_json::to_value(UnarchiveSessionResponse::new()).unwrap(),
8043            json!({})
8044        );
8045        assert_eq!(
8046            serde_json::to_value(
8047                SessionCapabilities::new().archive(SessionArchiveCapabilities::new())
8048            )
8049            .unwrap(),
8050            json!({"archive": {}})
8051        );
8052        assert_eq!(
8053            serde_json::to_value(
8054                ListSessionsRequest::new()
8055                    .cwd("/home/user/project")
8056                    .archived(SessionArchiveFilter::Only)
8057            )
8058            .unwrap(),
8059            json!({"cwd": "/home/user/project", "archived": "only"})
8060        );
8061        assert_eq!(
8062            serde_json::to_value(
8063                SessionInfo::new("sess_abc123", "/home/user/project").archived(true)
8064            )
8065            .unwrap(),
8066            json!({"sessionId": "sess_abc123", "cwd": "/home/user/project", "archived": true})
8067        );
8068    }
8069
8070    #[cfg(feature = "unstable_session_archive")]
8071    #[test]
8072    fn test_session_archive_filter_is_strict_and_open() {
8073        for (value, expected) in [
8074            (json!(null), None),
8075            (json!("include"), Some(SessionArchiveFilter::Include)),
8076            (
8077                json!("_recent"),
8078                Some(SessionArchiveFilter::Other("_recent".to_string())),
8079            ),
8080        ] {
8081            let request =
8082                serde_json::from_value::<ListSessionsRequest>(json!({"archived": value})).unwrap();
8083            assert_eq!(request.archived, expected);
8084        }
8085        for value in [json!(true), json!(1), json!({})] {
8086            assert!(
8087                serde_json::from_value::<ListSessionsRequest>(json!({"archived": value})).is_err()
8088            );
8089        }
8090        let info = serde_json::from_value::<SessionInfo>(
8091            json!({"sessionId": "sess_abc123", "cwd": "/home/user/project", "archived": "yes"}),
8092        )
8093        .unwrap();
8094        assert_eq!(info.archived, None);
8095    }
8096
8097    #[test]
8098    fn test_session_additional_directories_serialization() {
8099        assert_eq!(
8100            serde_json::to_value(NewSessionRequest::new("/home/user/project")).unwrap(),
8101            json!({
8102                "cwd": "/home/user/project",
8103                "mcpServers": []
8104            })
8105        );
8106        assert_eq!(
8107            serde_json::to_value(
8108                NewSessionRequest::new("/home/user/project").additional_directories(vec![
8109                    PathBuf::from("/home/user/shared-lib"),
8110                    PathBuf::from("/home/user/product-docs"),
8111                ])
8112            )
8113            .unwrap(),
8114            json!({
8115                "cwd": "/home/user/project",
8116                "additionalDirectories": [
8117                    "/home/user/shared-lib",
8118                    "/home/user/product-docs"
8119                ],
8120                "mcpServers": []
8121            })
8122        );
8123        assert_eq!(
8124            serde_json::to_value(SessionInfo::new("sess_abc123", "/home/user/project")).unwrap(),
8125            json!({
8126                "sessionId": "sess_abc123",
8127                "cwd": "/home/user/project"
8128            })
8129        );
8130        assert_eq!(
8131            serde_json::to_value(
8132                SessionInfo::new("sess_abc123", "/home/user/project").additional_directories(vec![
8133                    PathBuf::from("/home/user/shared-lib"),
8134                    PathBuf::from("/home/user/product-docs"),
8135                ])
8136            )
8137            .unwrap(),
8138            json!({
8139                "sessionId": "sess_abc123",
8140                "cwd": "/home/user/project",
8141                "additionalDirectories": [
8142                    "/home/user/shared-lib",
8143                    "/home/user/product-docs"
8144                ]
8145            })
8146        );
8147        assert_eq!(
8148            serde_json::from_value::<SessionInfo>(json!({
8149                "sessionId": "sess_abc123",
8150                "cwd": "/home/user/project"
8151            }))
8152            .unwrap()
8153            .additional_directories,
8154            Vec::<PathBuf>::new()
8155        );
8156    }
8157    #[test]
8158    fn test_session_additional_directories_capabilities_serialization() {
8159        assert_eq!(
8160            serde_json::to_value(
8161                SessionCapabilities::new()
8162                    .additional_directories(SessionAdditionalDirectoriesCapabilities::new())
8163            )
8164            .unwrap(),
8165            json!({
8166                "additionalDirectories": {}
8167            })
8168        );
8169    }
8170
8171    #[test]
8172    fn test_session_system_prompt_capabilities_serialization() {
8173        assert_eq!(
8174            serde_json::to_value(
8175                SessionCapabilities::new().system_prompt(SessionSystemPromptCapabilities::new())
8176            )
8177            .unwrap(),
8178            json!({ "systemPrompt": {} })
8179        );
8180        assert_eq!(
8181            serde_json::to_value(
8182                SessionCapabilities::new().system_prompt(
8183                    SessionSystemPromptCapabilities::new().mode(
8184                        SessionSystemPromptModeCapabilities::new()
8185                            .override_(SessionSystemPromptOverrideCapabilities::new())
8186                    )
8187                )
8188            )
8189            .unwrap(),
8190            json!({ "systemPrompt": { "mode": { "override": {} } } })
8191        );
8192        assert_eq!(
8193            serde_json::from_value::<SessionCapabilities>(
8194                json!({ "systemPrompt": { "mode": { "override": {} } } })
8195            )
8196            .unwrap()
8197            .system_prompt
8198            .and_then(|capabilities| capabilities.mode)
8199            .and_then(|mode| mode.override_),
8200            Some(SessionSystemPromptOverrideCapabilities::new())
8201        );
8202
8203        // Capabilities fall back to "not advertised" when malformed.
8204        assert_eq!(
8205            serde_json::from_value::<SessionCapabilities>(json!({ "systemPrompt": "yes" }))
8206                .unwrap()
8207                .system_prompt,
8208            None
8209        );
8210        assert_eq!(
8211            serde_json::from_value::<SessionCapabilities>(
8212                json!({ "systemPrompt": { "mode": { "override": true } } })
8213            )
8214            .unwrap()
8215            .system_prompt,
8216            Some(
8217                SessionSystemPromptCapabilities::new()
8218                    .mode(SessionSystemPromptModeCapabilities::new())
8219            )
8220        );
8221        assert_eq!(
8222            serde_json::from_value::<SessionCapabilities>(
8223                json!({ "systemPrompt": { "mode": "override" } })
8224            )
8225            .unwrap()
8226            .system_prompt,
8227            Some(SessionSystemPromptCapabilities::new())
8228        );
8229    }
8230
8231    #[test]
8232    fn test_system_prompt_lifecycle_request_serialization() {
8233        let system_prompt = SystemPrompt::new(vec![ContentBlock::from(
8234            "You are a code review specialist.",
8235        )]);
8236        let system_prompt_json = json!({
8237            "mode": "append",
8238            "content": [{ "type": "text", "text": "You are a code review specialist." }]
8239        });
8240
8241        let request =
8242            NewSessionRequest::new("/home/user/project").system_prompt(system_prompt.clone());
8243        let request_json = json!({
8244            "cwd": "/home/user/project",
8245            "mcpServers": [],
8246            "systemPrompt": system_prompt_json
8247        });
8248        assert_eq!(serde_json::to_value(&request).unwrap(), request_json);
8249        assert_eq!(
8250            serde_json::from_value::<NewSessionRequest>(request_json).unwrap(),
8251            request
8252        );
8253
8254        assert_eq!(
8255            serde_json::to_value(
8256                LoadSessionRequest::new("sess_abc123", "/home/user/project")
8257                    .system_prompt(system_prompt.clone())
8258            )
8259            .unwrap()["systemPrompt"],
8260            system_prompt_json
8261        );
8262        assert_eq!(
8263            serde_json::to_value(
8264                ResumeSessionRequest::new("sess_abc123", "/home/user/project")
8265                    .system_prompt(system_prompt.clone())
8266            )
8267            .unwrap()["systemPrompt"],
8268            system_prompt_json
8269        );
8270        #[cfg(feature = "unstable_session_fork")]
8271        assert_eq!(
8272            serde_json::to_value(
8273                ForkSessionRequest::new("sess_abc123", "/home/user/project")
8274                    .system_prompt(system_prompt.clone())
8275            )
8276            .unwrap()["systemPrompt"],
8277            system_prompt_json
8278        );
8279
8280        let override_prompt =
8281            SystemPrompt::new(vec![ContentBlock::from("...")]).mode(SystemPromptMode::Override);
8282        let override_json = json!({
8283            "mode": "override",
8284            "content": [{ "type": "text", "text": "..." }]
8285        });
8286        assert_eq!(
8287            serde_json::to_value(&override_prompt).unwrap(),
8288            override_json
8289        );
8290        assert_eq!(
8291            serde_json::from_value::<SystemPrompt>(override_json).unwrap(),
8292            override_prompt
8293        );
8294    }
8295
8296    /// `SystemPrompt::new` defaults to `append` in Rust, but `mode` is required on
8297    /// the wire, so it is always serialized.
8298    #[test]
8299    fn test_system_prompt_new_defaults_to_append() {
8300        let system_prompt = SystemPrompt::new(vec![ContentBlock::from("...")]);
8301        assert_eq!(system_prompt.mode, SystemPromptMode::Append);
8302        assert_eq!(
8303            serde_json::to_value(&system_prompt).unwrap(),
8304            json!({ "mode": "append", "content": [{ "type": "text", "text": "..." }] })
8305        );
8306    }
8307
8308    /// Unknown modes follow the enum variant extension rule: they parse as
8309    /// `SystemPromptMode::Other` so they are not dropped, and an agent that does
8310    /// not support them must reject the request.
8311    #[test]
8312    fn test_system_prompt_preserves_unknown_modes() {
8313        for mode in ["_vendor_mode", "prepend"] {
8314            let system_prompt_json =
8315                json!({ "mode": mode, "content": [{ "type": "text", "text": "..." }] });
8316            let system_prompt: SystemPrompt =
8317                serde_json::from_value(system_prompt_json.clone()).unwrap();
8318            assert_eq!(
8319                system_prompt.mode,
8320                SystemPromptMode::Other(mode.to_string())
8321            );
8322            assert_eq!(
8323                serde_json::to_value(&system_prompt).unwrap(),
8324                system_prompt_json
8325            );
8326        }
8327    }
8328
8329    /// The receiver acts on `systemPrompt`, so malformed values fail the request
8330    /// (`-32602`) instead of creating a session without the prompt, and `null`
8331    /// is equivalent to omitting the field.
8332    fn assert_system_prompt_is_strict<T>(base: &serde_json::Value)
8333    where
8334        T: serde::de::DeserializeOwned + PartialEq + std::fmt::Debug,
8335    {
8336        let name = std::any::type_name::<T>();
8337        let with = |system_prompt: serde_json::Value| {
8338            let mut request = base.clone();
8339            request["systemPrompt"] = system_prompt;
8340            serde_json::from_value::<T>(request)
8341        };
8342
8343        for system_prompt in [
8344            json!("You are a code review specialist."),
8345            json!({ "content": [{ "type": "text", "text": "..." }] }),
8346            json!({ "mode": null, "content": [{ "type": "text", "text": "..." }] }),
8347            json!({ "mode": 1, "content": [{ "type": "text", "text": "..." }] }),
8348            json!({ "mode": "append" }),
8349            json!({ "mode": "append", "content": "..." }),
8350            json!({ "mode": "append", "content": [{ "type": "text" }] }),
8351            json!({ "mode": "append", "content": [{ "type": "video", "uri": "..." }] }),
8352        ] {
8353            assert!(
8354                with(system_prompt.clone()).is_err(),
8355                "{name}.systemPrompt: {system_prompt}"
8356            );
8357        }
8358
8359        assert_eq!(
8360            with(serde_json::Value::Null).unwrap(),
8361            serde_json::from_value::<T>(base.clone()).unwrap(),
8362            "{name}.systemPrompt"
8363        );
8364    }
8365
8366    #[test]
8367    fn test_session_setup_requests_reject_malformed_system_prompts() {
8368        assert!(
8369            serde_json::to_value(NewSessionRequest::new("/repo"))
8370                .unwrap()
8371                .get("systemPrompt")
8372                .is_none()
8373        );
8374        assert_system_prompt_is_strict::<NewSessionRequest>(&json!({
8375            "cwd": "/repo",
8376            "mcpServers": []
8377        }));
8378        assert_system_prompt_is_strict::<LoadSessionRequest>(&json!({
8379            "sessionId": "sess-1",
8380            "cwd": "/repo",
8381            "mcpServers": []
8382        }));
8383        assert_system_prompt_is_strict::<ResumeSessionRequest>(&json!({
8384            "sessionId": "sess-1",
8385            "cwd": "/repo"
8386        }));
8387        #[cfg(feature = "unstable_session_fork")]
8388        assert_system_prompt_is_strict::<ForkSessionRequest>(&json!({
8389            "sessionId": "sess-1",
8390            "cwd": "/repo"
8391        }));
8392    }
8393
8394    #[test]
8395    fn test_auth_method_terminal_serialization() {
8396        let method = AuthMethod::Terminal(AuthMethodTerminal::new("tui-auth", "Terminal Auth"));
8397
8398        let json = serde_json::to_value(&method).unwrap();
8399        assert_eq!(
8400            json,
8401            json!({
8402                "id": "tui-auth",
8403                "name": "Terminal Auth",
8404                "type": "terminal"
8405            })
8406        );
8407        // args and env should be omitted when empty
8408        assert!(!json.as_object().unwrap().contains_key("args"));
8409        assert!(!json.as_object().unwrap().contains_key("env"));
8410
8411        let deserialized: AuthMethod = serde_json::from_value(json).unwrap();
8412        match deserialized {
8413            AuthMethod::Terminal(AuthMethodTerminal { args, env, .. }) => {
8414                assert_eq!(args, Vec::<String>::new());
8415                assert!(env.is_empty());
8416            }
8417            _ => panic!("Expected Terminal variant"),
8418        }
8419    }
8420
8421    #[test]
8422    fn test_auth_method_terminal_with_args_and_env_serialization() {
8423        use std::collections::HashMap;
8424
8425        let mut env = HashMap::new();
8426        env.insert("TERM".to_string(), "xterm-256color".to_string());
8427
8428        let method = AuthMethod::Terminal(
8429            AuthMethodTerminal::new("tui-auth", "Terminal Auth")
8430                .args(vec!["--interactive".to_string(), "--color".to_string()])
8431                .env(env),
8432        );
8433
8434        let json = serde_json::to_value(&method).unwrap();
8435        assert_eq!(
8436            json,
8437            json!({
8438                "id": "tui-auth",
8439                "name": "Terminal Auth",
8440                "type": "terminal",
8441                "args": ["--interactive", "--color"],
8442                "env": {
8443                    "TERM": "xterm-256color"
8444                }
8445            })
8446        );
8447
8448        let deserialized: AuthMethod = serde_json::from_value(json).unwrap();
8449        match deserialized {
8450            AuthMethod::Terminal(AuthMethodTerminal { args, env, .. }) => {
8451                assert_eq!(args, vec!["--interactive", "--color"]);
8452                assert_eq!(env.len(), 1);
8453                assert_eq!(env.get("TERM").unwrap(), "xterm-256color");
8454            }
8455            _ => panic!("Expected Terminal variant"),
8456        }
8457    }
8458
8459    #[test]
8460    fn test_session_config_option_value_id_serialize() {
8461        let val = SessionConfigOptionValue::value_id("model-1");
8462        let json = serde_json::to_value(&val).unwrap();
8463        // ValueId omits the "type" field (it's the default)
8464        assert_eq!(json, json!({ "value": "model-1" }));
8465        assert!(!json.as_object().unwrap().contains_key("type"));
8466    }
8467
8468    #[test]
8469    fn test_session_config_option_value_boolean_serialize() {
8470        let val = SessionConfigOptionValue::boolean(true);
8471        let json = serde_json::to_value(&val).unwrap();
8472        assert_eq!(json, json!({ "type": "boolean", "value": true }));
8473    }
8474
8475    #[test]
8476    fn test_session_config_option_value_deserialize_no_type() {
8477        // Missing "type" should default to ValueId
8478        let json = json!({ "value": "model-1" });
8479        let val: SessionConfigOptionValue = serde_json::from_value(json).unwrap();
8480        assert_eq!(val, SessionConfigOptionValue::value_id("model-1"));
8481        assert_eq!(val.as_value_id().unwrap().to_string(), "model-1");
8482    }
8483
8484    #[test]
8485    fn test_session_config_option_value_deserialize_boolean() {
8486        let json = json!({ "type": "boolean", "value": true });
8487        let val: SessionConfigOptionValue = serde_json::from_value(json).unwrap();
8488        assert_eq!(val, SessionConfigOptionValue::boolean(true));
8489        assert_eq!(val.as_bool(), Some(true));
8490    }
8491
8492    #[test]
8493    fn test_session_config_option_value_deserialize_boolean_false() {
8494        let json = json!({ "type": "boolean", "value": false });
8495        let val: SessionConfigOptionValue = serde_json::from_value(json).unwrap();
8496        assert_eq!(val, SessionConfigOptionValue::boolean(false));
8497        assert_eq!(val.as_bool(), Some(false));
8498    }
8499
8500    #[test]
8501    fn test_session_config_option_value_deserialize_unknown_type_with_string_value() {
8502        // Unknown type with a string value gracefully falls back to ValueId
8503        let json = json!({ "type": "text", "value": "freeform input" });
8504        let val: SessionConfigOptionValue = serde_json::from_value(json).unwrap();
8505        assert_eq!(val.as_value_id().unwrap().to_string(), "freeform input");
8506    }
8507
8508    #[test]
8509    fn test_session_config_option_value_roundtrip_value_id() {
8510        let original = SessionConfigOptionValue::value_id("option-a");
8511        let json = serde_json::to_value(&original).unwrap();
8512        let roundtripped: SessionConfigOptionValue = serde_json::from_value(json).unwrap();
8513        assert_eq!(original, roundtripped);
8514    }
8515
8516    #[test]
8517    fn test_session_config_option_value_roundtrip_boolean() {
8518        let original = SessionConfigOptionValue::boolean(false);
8519        let json = serde_json::to_value(&original).unwrap();
8520        let roundtripped: SessionConfigOptionValue = serde_json::from_value(json).unwrap();
8521        assert_eq!(original, roundtripped);
8522    }
8523
8524    #[test]
8525    fn test_session_config_option_value_type_mismatch_boolean_with_string() {
8526        // type says "boolean" but value is a string — falls to untagged ValueId
8527        let json = json!({ "type": "boolean", "value": "not a bool" });
8528        let result = serde_json::from_value::<SessionConfigOptionValue>(json);
8529        // serde tries Boolean first (fails), then falls to untagged ValueId (succeeds)
8530        assert!(result.is_ok());
8531        assert_eq!(
8532            result.unwrap().as_value_id().unwrap().to_string(),
8533            "not a bool"
8534        );
8535    }
8536
8537    #[test]
8538    fn test_session_config_option_value_from_impls() {
8539        let from_str: SessionConfigOptionValue = "model-1".into();
8540        assert_eq!(from_str.as_value_id().unwrap().to_string(), "model-1");
8541
8542        let from_id: SessionConfigOptionValue = SessionConfigValueId::new("model-2").into();
8543        assert_eq!(from_id.as_value_id().unwrap().to_string(), "model-2");
8544
8545        let from_bool: SessionConfigOptionValue = true.into();
8546        assert_eq!(from_bool.as_bool(), Some(true));
8547    }
8548
8549    #[test]
8550    fn test_set_session_config_option_request_value_id() {
8551        let req = SetSessionConfigOptionRequest::new("sess_1", "model", "model-1");
8552        let json = serde_json::to_value(&req).unwrap();
8553        assert_eq!(
8554            json,
8555            json!({
8556                "sessionId": "sess_1",
8557                "configId": "model",
8558                "value": "model-1"
8559            })
8560        );
8561        // No "type" field for value_id
8562        assert!(!json.as_object().unwrap().contains_key("type"));
8563    }
8564
8565    #[test]
8566    fn test_set_session_config_option_request_boolean() {
8567        let req = SetSessionConfigOptionRequest::new("sess_1", "brave_mode", true);
8568        let json = serde_json::to_value(&req).unwrap();
8569        assert_eq!(
8570            json,
8571            json!({
8572                "sessionId": "sess_1",
8573                "configId": "brave_mode",
8574                "type": "boolean",
8575                "value": true
8576            })
8577        );
8578    }
8579
8580    #[test]
8581    fn test_set_session_config_option_request_deserialize_no_type() {
8582        // Backwards-compatible: no "type" field → value_id
8583        let json = json!({
8584            "sessionId": "sess_1",
8585            "configId": "model",
8586            "value": "model-1"
8587        });
8588        let req: SetSessionConfigOptionRequest = serde_json::from_value(json).unwrap();
8589        assert_eq!(req.session_id.to_string(), "sess_1");
8590        assert_eq!(req.config_id.to_string(), "model");
8591        assert_eq!(req.value.as_value_id().unwrap().to_string(), "model-1");
8592    }
8593
8594    #[test]
8595    fn test_set_session_config_option_request_deserialize_boolean() {
8596        let json = json!({
8597            "sessionId": "sess_1",
8598            "configId": "brave_mode",
8599            "type": "boolean",
8600            "value": true
8601        });
8602        let req: SetSessionConfigOptionRequest = serde_json::from_value(json).unwrap();
8603        assert_eq!(req.value.as_bool(), Some(true));
8604    }
8605
8606    #[test]
8607    fn test_set_session_config_option_request_roundtrip_value_id() {
8608        let original = SetSessionConfigOptionRequest::new("s", "c", "v");
8609        let json = serde_json::to_value(&original).unwrap();
8610        let roundtripped: SetSessionConfigOptionRequest = serde_json::from_value(json).unwrap();
8611        assert_eq!(original, roundtripped);
8612    }
8613
8614    #[test]
8615    fn test_set_session_config_option_request_roundtrip_boolean() {
8616        let original = SetSessionConfigOptionRequest::new("s", "c", false);
8617        let json = serde_json::to_value(&original).unwrap();
8618        let roundtripped: SetSessionConfigOptionRequest = serde_json::from_value(json).unwrap();
8619        assert_eq!(original, roundtripped);
8620    }
8621
8622    #[test]
8623    fn test_session_config_boolean_serialization() {
8624        let cfg = SessionConfigBoolean::new(true);
8625        let json = serde_json::to_value(&cfg).unwrap();
8626        assert_eq!(json, json!({ "currentValue": true }));
8627
8628        let deserialized: SessionConfigBoolean = serde_json::from_value(json).unwrap();
8629        assert!(deserialized.current_value);
8630    }
8631
8632    #[test]
8633    fn test_session_config_option_boolean_variant() {
8634        let opt = SessionConfigOption::boolean("brave_mode", "Brave Mode", false)
8635            .description("Skip confirmation prompts")
8636            .meta(test_meta());
8637        assert_eq!(serialized_meta_key_count(&opt), 1);
8638
8639        let json = serde_json::to_value(&opt).unwrap();
8640        assert_eq!(
8641            json,
8642            json!({
8643                "id": "brave_mode",
8644                "name": "Brave Mode",
8645                "description": "Skip confirmation prompts",
8646                "type": "boolean",
8647                "currentValue": false,
8648                "_meta": {
8649                    "source": "test"
8650                }
8651            })
8652        );
8653
8654        let deserialized: SessionConfigOption = serde_json::from_value(json).unwrap();
8655        assert_eq!(deserialized.id.to_string(), "brave_mode");
8656        assert_eq!(deserialized.name, "Brave Mode");
8657        match deserialized.kind {
8658            SessionConfigKind::Boolean(ref b) => assert!(!b.current_value),
8659            _ => panic!("Expected Boolean kind"),
8660        }
8661    }
8662
8663    #[test]
8664    fn test_session_config_option_select_still_works() {
8665        // Make sure existing select options are unaffected
8666        let opt = SessionConfigOption::select(
8667            "model",
8668            "Model",
8669            "model-1",
8670            vec![
8671                SessionConfigSelectOption::new("model-1", "Model 1"),
8672                SessionConfigSelectOption::new("model-2", "Model 2"),
8673            ],
8674        )
8675        .meta(test_meta());
8676        assert_eq!(serialized_meta_key_count(&opt), 1);
8677
8678        let json = serde_json::to_value(&opt).unwrap();
8679        assert_eq!(json["type"], "select");
8680        assert_eq!(json["currentValue"], "model-1");
8681        assert_eq!(json["options"].as_array().unwrap().len(), 2);
8682        assert_eq!(json["_meta"]["source"], "test");
8683
8684        let deserialized: SessionConfigOption = serde_json::from_value(json).unwrap();
8685        match deserialized.kind {
8686            SessionConfigKind::Select(ref s) => {
8687                assert_eq!(s.current_value.to_string(), "model-1");
8688            }
8689            _ => panic!("Expected Select kind"),
8690        }
8691    }
8692
8693    #[cfg(feature = "unstable_llm_providers")]
8694    #[test]
8695    fn test_llm_protocol_known_variants() {
8696        assert_eq!(
8697            serde_json::to_value(&LlmProtocol::Anthropic).unwrap(),
8698            json!("anthropic")
8699        );
8700        assert_eq!(
8701            serde_json::to_value(&LlmProtocol::OpenAi).unwrap(),
8702            json!("openai")
8703        );
8704        assert_eq!(
8705            serde_json::to_value(&LlmProtocol::Azure).unwrap(),
8706            json!("azure")
8707        );
8708        assert_eq!(
8709            serde_json::to_value(&LlmProtocol::Vertex).unwrap(),
8710            json!("vertex")
8711        );
8712        assert_eq!(
8713            serde_json::to_value(&LlmProtocol::Bedrock).unwrap(),
8714            json!("bedrock")
8715        );
8716
8717        assert_eq!(
8718            serde_json::from_str::<LlmProtocol>("\"anthropic\"").unwrap(),
8719            LlmProtocol::Anthropic
8720        );
8721        assert_eq!(
8722            serde_json::from_str::<LlmProtocol>("\"openai\"").unwrap(),
8723            LlmProtocol::OpenAi
8724        );
8725        assert_eq!(
8726            serde_json::from_str::<LlmProtocol>("\"azure\"").unwrap(),
8727            LlmProtocol::Azure
8728        );
8729        assert_eq!(
8730            serde_json::from_str::<LlmProtocol>("\"vertex\"").unwrap(),
8731            LlmProtocol::Vertex
8732        );
8733        assert_eq!(
8734            serde_json::from_str::<LlmProtocol>("\"bedrock\"").unwrap(),
8735            LlmProtocol::Bedrock
8736        );
8737    }
8738
8739    #[cfg(feature = "unstable_llm_providers")]
8740    #[test]
8741    fn test_llm_protocol_unknown_variant() {
8742        let unknown: LlmProtocol = serde_json::from_str("\"cohere\"").unwrap();
8743        assert_eq!(unknown, LlmProtocol::Other("cohere".to_string()));
8744
8745        let json = serde_json::to_value(&unknown).unwrap();
8746        assert_eq!(json, json!("cohere"));
8747    }
8748
8749    #[cfg(feature = "unstable_llm_providers")]
8750    #[test]
8751    fn test_provider_current_config_serialization() {
8752        let config =
8753            ProviderCurrentConfig::new(LlmProtocol::Anthropic, "https://api.anthropic.com");
8754
8755        let json = serde_json::to_value(&config).unwrap();
8756        assert_eq!(
8757            json,
8758            json!({
8759                "apiType": "anthropic",
8760                "baseUrl": "https://api.anthropic.com"
8761            })
8762        );
8763
8764        let deserialized: ProviderCurrentConfig = serde_json::from_value(json).unwrap();
8765        assert_eq!(deserialized.api_type, LlmProtocol::Anthropic);
8766        assert_eq!(deserialized.base_url, "https://api.anthropic.com");
8767    }
8768
8769    #[cfg(feature = "unstable_llm_providers")]
8770    #[test]
8771    fn test_provider_info_with_current_config() {
8772        let info = ProviderInfo::new(
8773            "main",
8774            vec![LlmProtocol::Anthropic, LlmProtocol::OpenAi],
8775            true,
8776            Some(ProviderCurrentConfig::new(
8777                LlmProtocol::Anthropic,
8778                "https://api.anthropic.com",
8779            )),
8780        );
8781
8782        let json = serde_json::to_value(&info).unwrap();
8783        assert_eq!(
8784            json,
8785            json!({
8786                "providerId": "main",
8787                "supported": ["anthropic", "openai"],
8788                "required": true,
8789                "current": {
8790                    "apiType": "anthropic",
8791                    "baseUrl": "https://api.anthropic.com"
8792                }
8793            })
8794        );
8795
8796        let deserialized: ProviderInfo = serde_json::from_value(json).unwrap();
8797        assert_eq!(deserialized.provider_id.to_string(), "main");
8798        assert_eq!(deserialized.supported.len(), 2);
8799        assert!(deserialized.required);
8800        assert!(deserialized.current.is_some());
8801        assert_eq!(
8802            deserialized.current.as_ref().unwrap().api_type,
8803            LlmProtocol::Anthropic
8804        );
8805    }
8806
8807    #[cfg(feature = "unstable_llm_providers")]
8808    #[test]
8809    fn test_provider_info_disabled() {
8810        let info = ProviderInfo::new(
8811            "secondary",
8812            vec![LlmProtocol::OpenAi],
8813            false,
8814            None::<ProviderCurrentConfig>,
8815        );
8816
8817        let json = serde_json::to_value(&info).unwrap();
8818        assert_eq!(
8819            json,
8820            json!({
8821                "providerId": "secondary",
8822                "supported": ["openai"],
8823                "required": false
8824            })
8825        );
8826
8827        let deserialized: ProviderInfo = serde_json::from_value(json).unwrap();
8828        assert_eq!(deserialized.provider_id.to_string(), "secondary");
8829        assert!(!deserialized.required);
8830        assert!(deserialized.current.is_none());
8831    }
8832
8833    #[cfg(feature = "unstable_llm_providers")]
8834    #[test]
8835    fn test_provider_info_missing_current_defaults_to_none() {
8836        // current is optional; omitting it should decode as None
8837        let json = json!({
8838            "providerId": "main",
8839            "supported": ["anthropic"],
8840            "required": true
8841        });
8842        let deserialized: ProviderInfo = serde_json::from_value(json).unwrap();
8843        assert!(deserialized.current.is_none());
8844    }
8845
8846    #[cfg(feature = "unstable_llm_providers")]
8847    #[test]
8848    fn test_provider_info_explicit_null_current_decodes_to_none() {
8849        // current: null and an omitted current are equivalent on the wire;
8850        // both must deserialize into None so the disabled state is preserved
8851        // regardless of which form the peer chose to send.
8852        let json = json!({
8853            "providerId": "main",
8854            "supported": ["anthropic"],
8855            "required": true,
8856            "current": null
8857        });
8858        let deserialized: ProviderInfo = serde_json::from_value(json).unwrap();
8859        assert!(deserialized.current.is_none());
8860    }
8861
8862    #[cfg(feature = "unstable_llm_providers")]
8863    #[test]
8864    fn test_list_providers_response_serialization() {
8865        let response = ListProvidersResponse::new(vec![ProviderInfo::new(
8866            "main",
8867            vec![LlmProtocol::Anthropic],
8868            true,
8869            Some(ProviderCurrentConfig::new(
8870                LlmProtocol::Anthropic,
8871                "https://api.anthropic.com",
8872            )),
8873        )]);
8874
8875        let json = serde_json::to_value(&response).unwrap();
8876        assert_eq!(json["providers"].as_array().unwrap().len(), 1);
8877        assert_eq!(json["providers"][0]["providerId"], "main");
8878
8879        let deserialized: ListProvidersResponse = serde_json::from_value(json).unwrap();
8880        assert_eq!(deserialized.providers.len(), 1);
8881    }
8882
8883    #[cfg(feature = "unstable_llm_providers")]
8884    #[test]
8885    fn test_set_provider_request_serialization() {
8886        let mut headers = IndexMap::new();
8887        headers.insert("Authorization".to_string(), "Bearer sk-test".to_string());
8888
8889        let request =
8890            SetProviderRequest::new("main", LlmProtocol::OpenAi, "https://api.openai.com/v1")
8891                .headers(headers);
8892
8893        let json = serde_json::to_value(&request).unwrap();
8894        assert_eq!(
8895            json,
8896            json!({
8897                "providerId": "main",
8898                "apiType": "openai",
8899                "baseUrl": "https://api.openai.com/v1",
8900                "headers": {
8901                    "Authorization": "Bearer sk-test"
8902                }
8903            })
8904        );
8905
8906        let deserialized: SetProviderRequest = serde_json::from_value(json).unwrap();
8907        assert_eq!(deserialized.provider_id.to_string(), "main");
8908        assert_eq!(deserialized.api_type, LlmProtocol::OpenAi);
8909        assert_eq!(deserialized.base_url, "https://api.openai.com/v1");
8910        assert_eq!(deserialized.headers.len(), 1);
8911        assert_eq!(
8912            deserialized.headers.get("Authorization").unwrap(),
8913            "Bearer sk-test"
8914        );
8915    }
8916
8917    #[cfg(feature = "unstable_llm_providers")]
8918    #[test]
8919    fn test_set_provider_request_omits_empty_headers() {
8920        let request =
8921            SetProviderRequest::new("main", LlmProtocol::Anthropic, "https://api.anthropic.com");
8922
8923        let json = serde_json::to_value(&request).unwrap();
8924        // headers should be omitted when empty
8925        assert!(!json.as_object().unwrap().contains_key("headers"));
8926    }
8927
8928    #[cfg(feature = "unstable_llm_providers")]
8929    #[test]
8930    fn test_disable_provider_request_serialization() {
8931        let request = DisableProviderRequest::new("secondary");
8932
8933        let json = serde_json::to_value(&request).unwrap();
8934        assert_eq!(json, json!({ "providerId": "secondary" }));
8935
8936        let deserialized: DisableProviderRequest = serde_json::from_value(json).unwrap();
8937        assert_eq!(deserialized.provider_id.to_string(), "secondary");
8938    }
8939
8940    #[cfg(feature = "unstable_llm_providers")]
8941    #[test]
8942    fn test_providers_capabilities_serialization() {
8943        let caps = ProvidersCapabilities::new();
8944
8945        let json = serde_json::to_value(&caps).unwrap();
8946        assert_eq!(json, json!({}));
8947
8948        let deserialized: ProvidersCapabilities = serde_json::from_value(json).unwrap();
8949        assert!(deserialized.meta.is_none());
8950    }
8951
8952    #[cfg(feature = "unstable_llm_providers")]
8953    #[test]
8954    fn test_agent_capabilities_with_providers() {
8955        let caps = AgentCapabilities::new().providers(ProvidersCapabilities::new());
8956
8957        let json = serde_json::to_value(&caps).unwrap();
8958        assert_eq!(json["providers"], json!({}));
8959
8960        let deserialized: AgentCapabilities = serde_json::from_value(json).unwrap();
8961        assert!(deserialized.providers.is_some());
8962    }
8963
8964    #[test]
8965    fn prompt_request_rejects_malformed_content_block() {
8966        use serde_json::json;
8967
8968        assert!(
8969            serde_json::from_value::<PromptRequest>(json!({
8970                "sessionId": "sess-1",
8971                "prompt": [{"type": "text"}]
8972            }))
8973            .is_err()
8974        );
8975    }
8976
8977    #[test]
8978    fn prompt_request_rejects_non_array_prompt() {
8979        use serde_json::json;
8980
8981        assert!(
8982            serde_json::from_value::<PromptRequest>(json!({
8983                "sessionId": "sess-1",
8984                "prompt": "hello"
8985            }))
8986            .is_err()
8987        );
8988    }
8989
8990    fn assert_session_setup_lists_are_strict<T>(base: &serde_json::Value)
8991    where
8992        T: serde::de::DeserializeOwned + PartialEq + std::fmt::Debug,
8993    {
8994        let name = std::any::type_name::<T>();
8995        let with = |field: &str, value: serde_json::Value| {
8996            let mut request = base.clone();
8997            request[field] = value;
8998            serde_json::from_value::<T>(request)
8999        };
9000
9001        for (field, value) in [
9002            // Dropping the malformed server would start the session without it.
9003            (
9004                "mcpServers",
9005                json!([
9006                    {"name": "github", "command": "/usr/bin/gh-mcp", "args": [], "env": [{"name": "GITHUB_TOKEN", "value": null}]},
9007                    {"name": "fs", "command": "/usr/bin/fs-mcp", "args": [], "env": []}
9008                ]),
9009            ),
9010            ("mcpServers", json!({"name": "fs"})),
9011            ("additionalDirectories", json!(["/repo/lib", 42])),
9012            ("additionalDirectories", json!("/repo/lib")),
9013        ] {
9014            assert!(
9015                with(field, value.clone()).is_err(),
9016                "{name}.{field}: {value}"
9017            );
9018        }
9019
9020        let empty = serde_json::from_value::<T>(base.clone()).unwrap();
9021        for field in ["mcpServers", "additionalDirectories"] {
9022            assert_eq!(
9023                with(field, serde_json::Value::Null).unwrap(),
9024                empty,
9025                "{name}.{field}"
9026            );
9027        }
9028    }
9029
9030    #[test]
9031    fn session_setup_requests_reject_malformed_mcp_servers_and_directories() {
9032        assert_session_setup_lists_are_strict::<NewSessionRequest>(&json!({
9033            "cwd": "/repo",
9034            "mcpServers": []
9035        }));
9036        assert_session_setup_lists_are_strict::<LoadSessionRequest>(&json!({
9037            "sessionId": "sess-1",
9038            "cwd": "/repo",
9039            "mcpServers": []
9040        }));
9041        assert_session_setup_lists_are_strict::<ResumeSessionRequest>(&json!({
9042            "sessionId": "sess-1",
9043            "cwd": "/repo"
9044        }));
9045        #[cfg(feature = "unstable_session_fork")]
9046        assert_session_setup_lists_are_strict::<ForkSessionRequest>(&json!({
9047            "sessionId": "sess-1",
9048            "cwd": "/repo"
9049        }));
9050    }
9051
9052    #[test]
9053    fn mcp_server_lists_treat_null_as_empty() {
9054        let servers: Vec<McpServer> = serde_json::from_value(json!([
9055            {"name": "fs", "command": "/usr/bin/fs-mcp", "args": null, "env": null},
9056            {"type": "http", "name": "api", "url": "https://example.com/mcp", "headers": null},
9057            {"type": "sse", "name": "events", "url": "https://example.com/sse", "headers": null}
9058        ]))
9059        .unwrap();
9060
9061        assert_eq!(
9062            servers,
9063            vec![
9064                McpServer::Stdio(McpServerStdio::new("fs", "/usr/bin/fs-mcp")),
9065                McpServer::Http(McpServerHttp::new("api", "https://example.com/mcp")),
9066                McpServer::Sse(McpServerSse::new("events", "https://example.com/sse")),
9067            ]
9068        );
9069    }
9070
9071    #[test]
9072    fn terminal_auth_methods_reject_malformed_launch_config() {
9073        // The client spawns a process from `args` and `env`, so a malformed
9074        // method is dropped from `authMethods` instead of launched with
9075        // altered arguments or reinterpreted as an `agent` method.
9076        let response: InitializeResponse = serde_json::from_value(json!({
9077            "protocolVersion": 1,
9078            "authMethods": [
9079                {"type": "terminal", "id": "bad-args", "name": "Log in", "args": ["auth", "--port", 8123]},
9080                {"type": "terminal", "id": "bad-env", "name": "Log in", "env": {"AUTH_MODE": "device", "DEBUG": 1}},
9081                {"type": "terminal", "id": "null-config", "name": "Log in", "args": null, "env": null},
9082                {"id": "agent", "name": "Agent login"}
9083            ]
9084        }))
9085        .unwrap();
9086
9087        assert_eq!(
9088            response.auth_methods,
9089            vec![
9090                AuthMethod::Terminal(AuthMethodTerminal::new("null-config", "Log in")),
9091                AuthMethod::Agent(AuthMethodAgent::new("agent", "Agent login")),
9092            ]
9093        );
9094        assert!(
9095            serde_json::from_value::<AuthMethod>(json!({
9096                "type": "terminal",
9097                "id": "bad-args",
9098                "name": "Log in",
9099                "args": ["auth", 8123]
9100            }))
9101            .is_err()
9102        );
9103    }
9104
9105    #[cfg(feature = "unstable_auth_status")]
9106    #[test]
9107    fn auth_status_response_round_trips() {
9108        let response = AuthStatusResponse::new(AuthState::Authenticated).accounts(vec![
9109            AuthAccount::new("Anthropic API key")
9110                .description("API key helper".to_string())
9111                .active(true),
9112            AuthAccount::new("Claude Max").email("user@example.com".to_string()),
9113        ]);
9114        let json = serde_json::to_value(&response).unwrap();
9115        assert_eq!(
9116            json,
9117            json!({
9118                "state": "authenticated",
9119                "accounts": [
9120                    {
9121                        "label": "Anthropic API key",
9122                        "description": "API key helper",
9123                        "active": true
9124                    },
9125                    {
9126                        "label": "Claude Max",
9127                        "email": "user@example.com"
9128                    }
9129                ]
9130            })
9131        );
9132        assert_eq!(
9133            serde_json::from_value::<AuthStatusResponse>(json).unwrap(),
9134            response
9135        );
9136        assert_eq!(
9137            serde_json::to_value(AuthStatusResponse::new(AuthState::NotRequired)).unwrap(),
9138            json!({"state": "not_required"})
9139        );
9140    }
9141
9142    #[cfg(feature = "unstable_auth_status")]
9143    #[test]
9144    fn auth_status_state_is_strict_and_accounts_are_lenient() {
9145        assert!(serde_json::from_value::<AuthStatusResponse>(json!({})).is_err());
9146        assert!(serde_json::from_value::<AuthStatusResponse>(json!({"state": null})).is_err());
9147        assert!(serde_json::from_value::<AuthStatusResponse>(json!({"state": 1})).is_err());
9148
9149        let response: AuthStatusResponse = serde_json::from_value(json!({
9150            "state": "_vendor_state",
9151            "accounts": [
9152                {"active": true},
9153                {
9154                    "label": "Vertex AI",
9155                    "description": 42,
9156                    "active": "yes",
9157                    "email": ["not", "a", "string"]
9158                }
9159            ]
9160        }))
9161        .unwrap();
9162        assert_eq!(
9163            response,
9164            AuthStatusResponse::new(AuthState::Other("_vendor_state".to_string()))
9165                .accounts(vec![AuthAccount::new("Vertex AI")])
9166        );
9167        assert_eq!(
9168            serde_json::from_value::<AuthStatusResponse>(
9169                json!({"state": "unknown", "accounts": null})
9170            )
9171            .unwrap(),
9172            AuthStatusResponse::new(AuthState::Unknown)
9173        );
9174    }
9175
9176    #[cfg(feature = "unstable_auth_status")]
9177    #[test]
9178    fn auth_status_update_notification_routes() {
9179        use crate::v1::{AgentNotification, CLIENT_METHOD_NAMES};
9180
9181        assert_eq!(AGENT_METHOD_NAMES.auth_status, "auth/status");
9182        assert_eq!(CLIENT_METHOD_NAMES.auth_status_update, "auth/status_update");
9183        let notification = AgentNotification::AuthStatusUpdateNotification(
9184            AuthStatusUpdateNotification::new(AuthState::Unauthenticated),
9185        );
9186        assert_eq!(notification.method(), "auth/status_update");
9187        assert_eq!(
9188            serde_json::to_value(&notification).unwrap(),
9189            json!({"state": "unauthenticated"})
9190        );
9191    }
9192
9193    #[cfg(all(
9194        feature = "unstable_session_fork",
9195        feature = "unstable_session_cursors"
9196    ))]
9197    #[test]
9198    fn fork_session_request_cursor_id_is_optional_and_strict() {
9199        let request = ForkSessionRequest::new("sess_abc123", "/home/user/project")
9200            .cursor_id(CursorId::new("cur_1"));
9201        let wire = json!({
9202            "sessionId": "sess_abc123",
9203            "cursorId": "cur_1",
9204            "cwd": "/home/user/project"
9205        });
9206        assert_eq!(serde_json::to_value(&request).unwrap(), wire);
9207        assert_eq!(
9208            serde_json::from_value::<ForkSessionRequest>(wire).unwrap(),
9209            request
9210        );
9211
9212        // Omitted and `null` both fork the whole session.
9213        for wire in [
9214            json!({ "sessionId": "sess_abc123", "cwd": "/home/user/project" }),
9215            json!({ "sessionId": "sess_abc123", "cwd": "/home/user/project", "cursorId": null }),
9216        ] {
9217            assert_eq!(
9218                serde_json::from_value::<ForkSessionRequest>(wire)
9219                    .unwrap()
9220                    .cursor_id,
9221                None
9222            );
9223        }
9224
9225        // A malformed cursor ID fails the request. It never forks the whole session.
9226        assert!(
9227            serde_json::from_value::<ForkSessionRequest>(json!({
9228                "sessionId": "sess_abc123",
9229                "cwd": "/home/user/project",
9230                "cursorId": 7
9231            }))
9232            .is_err()
9233        );
9234    }
9235}