Skip to main content

agent_client_protocol_schema/v2/
protocol_level.rs

1use serde::{Deserialize, Serialize};
2use serde_with::{DefaultOnError, serde_as, skip_serializing_none};
3
4use super::{Meta, RequestId};
5use crate::IntoOption;
6
7/// Notification to cancel an ongoing request.
8///
9/// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/cancellation)
10#[serde_as]
11#[skip_serializing_none]
12#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
13#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
14#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "protocol", "x-method" = CANCEL_REQUEST_METHOD_NAME)))]
15#[serde(rename_all = "camelCase")]
16#[non_exhaustive]
17pub struct CancelRequestNotification {
18    /// The ID of the request to cancel: a request that the sender of this notification issued.
19    /// Receivers match it only against requests they received from that sender.
20    pub request_id: RequestId,
21    /// The _meta property is reserved by ACP to allow Clients and Agents to attach additional
22    /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata.
23    /// Implementations MUST NOT assign meaning to keys they do not recognize.
24    ///
25    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
26    #[serde_as(deserialize_as = "DefaultOnError")]
27    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
28    #[serde(default)]
29    #[serde(rename = "_meta")]
30    pub meta: Option<Meta>,
31}
32
33impl CancelRequestNotification {
34    /// Builds [`CancelRequestNotification`] with the required notification fields set. Optional fields start unset or empty.
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 assign meaning to keys they
45    /// do not recognize.
46    ///
47    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/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 the protocol-level methods, which both Agents and Clients 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    /// Method name for protocol-level request cancellation notifications.
64    pub cancel_request: &'static str,
65}
66
67/// Constant containing all protocol-level method names.
68pub const PROTOCOL_LEVEL_METHOD_NAMES: GeneralMethodNames = GeneralMethodNames {
69    cancel_request: CANCEL_REQUEST_METHOD_NAME,
70};
71
72/// Method name for general cancel notification
73pub(crate) const CANCEL_REQUEST_METHOD_NAME: &str = "$/cancel_request";
74
75/// Protocol-level notifications, which either side can send.
76///
77/// Their methods start with `$/`. Acting on one is optional, because it might not
78/// be implementable in every Client or Agent. For example, a single-threaded
79/// synchronous implementation can do little to react to a `$/cancel_request`
80/// notification. An Agent or Client MAY ignore a `$/` notification it cannot act on.
81///
82/// Notifications do not expect a response.
83#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
84#[derive(Clone, Debug, Serialize, Deserialize)]
85#[serde(untagged)]
86#[cfg_attr(feature = "schemars", schemars(inline))]
87#[non_exhaustive]
88pub enum ProtocolLevelNotification {
89    /// Cancels an ongoing request.
90    ///
91    /// This is a notification sent by the side that sent a request to cancel that request.
92    ///
93    /// Upon receiving this notification, the receiver:
94    ///
95    /// 1. MAY cancel the corresponding request activity and all nested activities
96    /// 2. MAY send any pending notifications.
97    /// 3. MUST still send a response for the original request. If the request already finished
98    ///    or is not cancelled, that is its normal response. If it is cancelled, it is either the
99    ///    method's defined cancellation result (for example an inserted `session/prompt`, or a
100    ///    `cancelled` permission outcome) or an error with code `-32800` (Request cancelled).
101    ///
102    /// Receivers MUST ignore this notification for an unknown or already-answered request ID,
103    /// and MUST NOT send a second response for it.
104    ///
105    /// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/cancellation)
106    CancelRequestNotification(CancelRequestNotification),
107}
108
109impl_message_dispatch! {
110    ProtocolLevelNotification {
111        CancelRequestNotification => PROTOCOL_LEVEL_METHOD_NAMES.cancel_request,
112    }
113}