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

agent_client_protocol_schema/v2/
protocol_level.rs
