agent_client_protocol_schema/v2/
protocol_level.rs

1use schemars::JsonSchema;
2use serde::{Deserialize, Serialize};
3use serde_with::skip_serializing_none;
4
5use super::{Meta, RequestId};
6use crate::IntoOption;
7
8/// **UNSTABLE**
9///
10/// This capability is not part of the spec yet, and may be removed or changed at any point.
11///
12/// Notification to cancel an ongoing request.
13///
14/// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation)
15#[cfg(feature = "unstable_cancel_request")]
16#[skip_serializing_none]
17#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
18#[schemars(extend("x-side" = "protocol", "x-method" = CANCEL_REQUEST_METHOD_NAME))]
19#[serde(rename_all = "camelCase")]
20#[non_exhaustive]
21pub struct CancelRequestNotification {
22    /// The ID of the request to cancel.
23    pub request_id: RequestId,
24    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
25    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
26    /// these keys.
27    ///
28    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
29    #[serde(rename = "_meta")]
30    pub meta: Option<Meta>,
31}
32
33#[cfg(feature = "unstable_cancel_request")]
34impl CancelRequestNotification {
35    /// Builds [`CancelRequestNotification`] with the required notification fields set; optional fields start unset or empty.
36    #[must_use]
37    pub fn new(request_id: impl Into<RequestId>) -> Self {
38        Self {
39            request_id: request_id.into(),
40            meta: None,
41        }
42    }
43
44    /// The _meta property is reserved by ACP to allow clients and agents to attach additional
45    /// metadata to their interactions. Implementations MUST NOT make assumptions about values at
46    /// these keys.
47    ///
48    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
49    #[must_use]
50    pub fn meta(mut self, meta: impl IntoOption<Meta>) -> Self {
51        self.meta = meta.into_option();
52        self
53    }
54}
55
56// Method schema
57
58/// Names of all methods that agents handle.
59///
60/// Provides a centralized definition of method names used in the protocol.
61#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
62#[non_exhaustive]
63pub struct GeneralMethodNames {
64    /// Method name for protocol-level request cancellation notifications.
65    #[cfg(feature = "unstable_cancel_request")]
66    pub cancel_request: &'static str,
67}
68
69/// Constant containing all agent method names.
70pub const PROTOCOL_LEVEL_METHOD_NAMES: GeneralMethodNames = GeneralMethodNames {
71    #[cfg(feature = "unstable_cancel_request")]
72    cancel_request: CANCEL_REQUEST_METHOD_NAME,
73};
74
75/// Method name for general cancel notification
76pub(crate) const CANCEL_REQUEST_METHOD_NAME: &str = "$/cancel_request";
77
78/// General protocol-level notifications that all sides are expected to
79/// implement.
80///
81/// Notifications whose methods start with '$/' are messages which
82/// are protocol implementation dependent and might not be implementable in all
83/// clients or agents. For example if the implementation uses a single threaded
84/// synchronous programming language then there is little it can do to react to
85/// a `$/cancel_request` notification. If an agent or client receives
86/// notifications starting with '$/' it is free to ignore the notification.
87///
88/// Notifications do not expect a response.
89#[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
90#[serde(untagged)]
91#[schemars(inline)]
92#[non_exhaustive]
93pub enum ProtocolLevelNotification {
94    /// **UNSTABLE**
95    ///
96    /// This capability is not part of the spec yet, and may be removed or
97    /// changed at any point.
98    ///
99    /// Cancels an ongoing request.
100    ///
101    /// This is a notification sent by the side that sent a request to cancel that request.
102    ///
103    /// Upon receiving this notification, the receiver:
104    ///
105    /// 1. MUST cancel the corresponding request activity and all nested activities
106    /// 2. MAY send any pending notifications.
107    /// 3. MUST send one of these responses for the original request:
108    ///   - Valid response with appropriate data (partial results or cancellation marker)
109    ///   - Error response with code `-32800` (Cancelled)
110    ///
111    /// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation)
112    #[cfg(feature = "unstable_cancel_request")]
113    CancelRequestNotification(CancelRequestNotification),
114}
115
116impl ProtocolLevelNotification {
117    /// Returns the corresponding method name of the notification.
118    #[must_use]
119    pub fn method(&self) -> &str {
120        match self {
121            #[cfg(feature = "unstable_cancel_request")]
122            Self::CancelRequestNotification(..) => PROTOCOL_LEVEL_METHOD_NAMES.cancel_request,
123        }
124    }
125}
agent_client_protocol_schema/v2/protocol_level.rs

agent_client_protocol_schema/v2/
protocol_level.rs
