diff --git a/agent-client-protocol-schema/Cargo.toml b/agent-client-protocol-schema/Cargo.toml index e77820a94..086d6ba7a 100644 --- a/agent-client-protocol-schema/Cargo.toml +++ b/agent-client-protocol-schema/Cargo.toml @@ -24,7 +24,6 @@ workspace = true [features] unstable = [ "unstable_auth_methods", - "unstable_cancel_request", "unstable_elicitation", "unstable_llm_providers", "unstable_mcp_over_acp", @@ -39,7 +38,6 @@ unstable = [ # version, so it must be opted into explicitly. unstable_protocol_v2 = [] unstable_auth_methods = [] -unstable_cancel_request = [] unstable_elicitation = [] unstable_llm_providers = [] unstable_mcp_over_acp = [] diff --git a/agent-client-protocol-schema/src/v1/error.rs b/agent-client-protocol-schema/src/v1/error.rs index dc688e4f4..ac4c55a7a 100644 --- a/agent-client-protocol-schema/src/v1/error.rs +++ b/agent-client-protocol-schema/src/v1/error.rs @@ -99,15 +99,10 @@ impl Error { ErrorCode::InternalError.into() } - /// **UNSTABLE** - /// - /// This capability is not part of the spec yet, and may be removed or changed at any point. - /// /// Request was cancelled. /// /// Execution of the method was aborted either due to a cancellation request from the caller /// or because of resource constraints or shutdown. - #[cfg(feature = "unstable_cancel_request")] #[must_use] pub fn request_cancelled() -> Self { ErrorCode::RequestCancelled.into() @@ -183,11 +178,6 @@ pub enum ErrorCode { #[schemars(transform = error_code_transform)] #[strum(to_string = "Internal error")] InternalError, // -32603 - #[cfg(feature = "unstable_cancel_request")] - /// **UNSTABLE** - /// - /// This capability is not part of the spec yet, and may be removed or changed at any point. - /// /// Execution of the method was aborted either due to a cancellation request from the caller or /// because of resource constraints or shutdown. #[schemars(transform = error_code_transform)] @@ -227,7 +217,6 @@ impl From for ErrorCode { -32601 => ErrorCode::MethodNotFound, -32602 => ErrorCode::InvalidParams, -32603 => ErrorCode::InternalError, - #[cfg(feature = "unstable_cancel_request")] -32800 => ErrorCode::RequestCancelled, -32000 => ErrorCode::AuthRequired, -32002 => ErrorCode::ResourceNotFound, @@ -246,7 +235,6 @@ impl From for i32 { ErrorCode::MethodNotFound => -32601, ErrorCode::InvalidParams => -32602, ErrorCode::InternalError => -32603, - #[cfg(feature = "unstable_cancel_request")] ErrorCode::RequestCancelled => -32800, ErrorCode::AuthRequired => -32000, ErrorCode::ResourceNotFound => -32002, @@ -275,7 +263,6 @@ fn error_code_transform(schema: &mut Schema) { "MethodNotFound" => ErrorCode::MethodNotFound, "InvalidParams" => ErrorCode::InvalidParams, "InternalError" => ErrorCode::InternalError, - #[cfg(feature = "unstable_cancel_request")] "RequestCancelled" => ErrorCode::RequestCancelled, "AuthRequired" => ErrorCode::AuthRequired, "ResourceNotFound" => ErrorCode::ResourceNotFound, diff --git a/agent-client-protocol-schema/src/v1/mod.rs b/agent-client-protocol-schema/src/v1/mod.rs index 0b8a37bdc..f26c02678 100644 --- a/agent-client-protocol-schema/src/v1/mod.rs +++ b/agent-client-protocol-schema/src/v1/mod.rs @@ -12,7 +12,6 @@ mod mcp; #[cfg(feature = "unstable_nes")] mod nes; mod plan; -#[cfg(feature = "unstable_cancel_request")] mod protocol_level; mod tool_call; @@ -30,7 +29,6 @@ pub use mcp::*; #[cfg(feature = "unstable_nes")] pub use nes::*; pub use plan::*; -#[cfg(feature = "unstable_cancel_request")] pub use protocol_level::*; pub use serde_json::value::RawValue; pub use tool_call::*; diff --git a/agent-client-protocol-schema/src/v1/protocol_level.rs b/agent-client-protocol-schema/src/v1/protocol_level.rs index a49d3a78f..54f873ede 100644 --- a/agent-client-protocol-schema/src/v1/protocol_level.rs +++ b/agent-client-protocol-schema/src/v1/protocol_level.rs @@ -6,14 +6,9 @@ use crate::IntoOption; use super::{Meta, RequestId}; -/// **UNSTABLE** -/// -/// This capability is not part of the spec yet, and may be removed or changed at any point. -/// /// Notification to cancel an ongoing request. /// /// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation) -#[cfg(feature = "unstable_cancel_request")] #[serde_as] #[skip_serializing_none] #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] @@ -35,7 +30,6 @@ pub struct CancelRequestNotification { pub meta: Option, } -#[cfg(feature = "unstable_cancel_request")] impl CancelRequestNotification { /// Builds [`CancelRequestNotification`] with the required notification fields set; optional fields start unset or empty. #[must_use] @@ -67,13 +61,11 @@ impl CancelRequestNotification { #[non_exhaustive] pub struct GeneralMethodNames { /// Method name for protocol-level request cancellation notifications. - #[cfg(feature = "unstable_cancel_request")] pub cancel_request: &'static str, } /// Constant containing all agent method names. pub const PROTOCOL_LEVEL_METHOD_NAMES: GeneralMethodNames = GeneralMethodNames { - #[cfg(feature = "unstable_cancel_request")] cancel_request: CANCEL_REQUEST_METHOD_NAME, }; @@ -96,25 +88,19 @@ pub(crate) const CANCEL_REQUEST_METHOD_NAME: &str = "$/cancel_request"; #[schemars(inline)] #[non_exhaustive] pub enum ProtocolLevelNotification { - /// **UNSTABLE** - /// - /// This capability is not part of the spec yet, and may be removed or - /// changed at any point. - /// /// Cancels an ongoing request. /// /// This is a notification sent by the side that sent a request to cancel that request. /// /// Upon receiving this notification, the receiver: /// - /// 1. MUST cancel the corresponding request activity and all nested activities + /// 1. MAY cancel the corresponding request activity and all nested activities /// 2. MAY send any pending notifications. /// 3. MUST send one of these responses for the original request: /// - Valid response with appropriate data (partial results or cancellation marker) /// - Error response with code `-32800` (Cancelled) /// /// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation) - #[cfg(feature = "unstable_cancel_request")] CancelRequestNotification(CancelRequestNotification), } @@ -123,7 +109,6 @@ impl ProtocolLevelNotification { #[must_use] pub fn method(&self) -> &str { match self { - #[cfg(feature = "unstable_cancel_request")] Self::CancelRequestNotification(..) => PROTOCOL_LEVEL_METHOD_NAMES.cancel_request, } } diff --git a/agent-client-protocol-schema/src/v2/conversion.rs b/agent-client-protocol-schema/src/v2/conversion.rs index 36bb4ef6e..8123c5c61 100644 --- a/agent-client-protocol-schema/src/v2/conversion.rs +++ b/agent-client-protocol-schema/src/v2/conversion.rs @@ -897,7 +897,6 @@ impl IntoV2 for crate::v1::PlanEntryStatus { } } -#[cfg(feature = "unstable_cancel_request")] impl IntoV1 for super::CancelRequestNotification { type Output = crate::v1::CancelRequestNotification; @@ -910,7 +909,6 @@ impl IntoV1 for super::CancelRequestNotification { } } -#[cfg(feature = "unstable_cancel_request")] impl IntoV2 for crate::v1::CancelRequestNotification { type Output = super::CancelRequestNotification; @@ -923,7 +921,6 @@ impl IntoV2 for crate::v1::CancelRequestNotification { } } -#[cfg(feature = "unstable_cancel_request")] impl IntoV1 for super::ProtocolLevelNotification { type Output = crate::v1::ProtocolLevelNotification; @@ -936,7 +933,6 @@ impl IntoV1 for super::ProtocolLevelNotification { } } -#[cfg(feature = "unstable_cancel_request")] impl IntoV2 for crate::v1::ProtocolLevelNotification { type Output = super::ProtocolLevelNotification; diff --git a/agent-client-protocol-schema/src/v2/error.rs b/agent-client-protocol-schema/src/v2/error.rs index dc688e4f4..ac4c55a7a 100644 --- a/agent-client-protocol-schema/src/v2/error.rs +++ b/agent-client-protocol-schema/src/v2/error.rs @@ -99,15 +99,10 @@ impl Error { ErrorCode::InternalError.into() } - /// **UNSTABLE** - /// - /// This capability is not part of the spec yet, and may be removed or changed at any point. - /// /// Request was cancelled. /// /// Execution of the method was aborted either due to a cancellation request from the caller /// or because of resource constraints or shutdown. - #[cfg(feature = "unstable_cancel_request")] #[must_use] pub fn request_cancelled() -> Self { ErrorCode::RequestCancelled.into() @@ -183,11 +178,6 @@ pub enum ErrorCode { #[schemars(transform = error_code_transform)] #[strum(to_string = "Internal error")] InternalError, // -32603 - #[cfg(feature = "unstable_cancel_request")] - /// **UNSTABLE** - /// - /// This capability is not part of the spec yet, and may be removed or changed at any point. - /// /// Execution of the method was aborted either due to a cancellation request from the caller or /// because of resource constraints or shutdown. #[schemars(transform = error_code_transform)] @@ -227,7 +217,6 @@ impl From for ErrorCode { -32601 => ErrorCode::MethodNotFound, -32602 => ErrorCode::InvalidParams, -32603 => ErrorCode::InternalError, - #[cfg(feature = "unstable_cancel_request")] -32800 => ErrorCode::RequestCancelled, -32000 => ErrorCode::AuthRequired, -32002 => ErrorCode::ResourceNotFound, @@ -246,7 +235,6 @@ impl From for i32 { ErrorCode::MethodNotFound => -32601, ErrorCode::InvalidParams => -32602, ErrorCode::InternalError => -32603, - #[cfg(feature = "unstable_cancel_request")] ErrorCode::RequestCancelled => -32800, ErrorCode::AuthRequired => -32000, ErrorCode::ResourceNotFound => -32002, @@ -275,7 +263,6 @@ fn error_code_transform(schema: &mut Schema) { "MethodNotFound" => ErrorCode::MethodNotFound, "InvalidParams" => ErrorCode::InvalidParams, "InternalError" => ErrorCode::InternalError, - #[cfg(feature = "unstable_cancel_request")] "RequestCancelled" => ErrorCode::RequestCancelled, "AuthRequired" => ErrorCode::AuthRequired, "ResourceNotFound" => ErrorCode::ResourceNotFound, diff --git a/agent-client-protocol-schema/src/v2/mod.rs b/agent-client-protocol-schema/src/v2/mod.rs index c8c1af7c8..577e6e71b 100644 --- a/agent-client-protocol-schema/src/v2/mod.rs +++ b/agent-client-protocol-schema/src/v2/mod.rs @@ -23,7 +23,6 @@ mod mcp; #[cfg(feature = "unstable_nes")] mod nes; mod plan; -#[cfg(feature = "unstable_cancel_request")] mod protocol_level; pub(crate) mod schema_util; mod tool_call; @@ -42,7 +41,6 @@ pub use mcp::*; #[cfg(feature = "unstable_nes")] pub use nes::*; pub use plan::*; -#[cfg(feature = "unstable_cancel_request")] pub use protocol_level::*; pub use serde_json::value::RawValue; pub use tool_call::*; diff --git a/agent-client-protocol-schema/src/v2/protocol_level.rs b/agent-client-protocol-schema/src/v2/protocol_level.rs index 714290b6b..d861cd597 100644 --- a/agent-client-protocol-schema/src/v2/protocol_level.rs +++ b/agent-client-protocol-schema/src/v2/protocol_level.rs @@ -5,14 +5,9 @@ use serde_with::{DefaultOnError, serde_as, skip_serializing_none}; use super::{Meta, RequestId}; use crate::IntoOption; -/// **UNSTABLE** -/// -/// This capability is not part of the spec yet, and may be removed or changed at any point. -/// /// Notification to cancel an ongoing request. /// /// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation) -#[cfg(feature = "unstable_cancel_request")] #[serde_as] #[skip_serializing_none] #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] @@ -34,7 +29,6 @@ pub struct CancelRequestNotification { pub meta: Option, } -#[cfg(feature = "unstable_cancel_request")] impl CancelRequestNotification { /// Builds [`CancelRequestNotification`] with the required notification fields set; optional fields start unset or empty. #[must_use] @@ -66,13 +60,11 @@ impl CancelRequestNotification { #[non_exhaustive] pub struct GeneralMethodNames { /// Method name for protocol-level request cancellation notifications. - #[cfg(feature = "unstable_cancel_request")] pub cancel_request: &'static str, } /// Constant containing all agent method names. pub const PROTOCOL_LEVEL_METHOD_NAMES: GeneralMethodNames = GeneralMethodNames { - #[cfg(feature = "unstable_cancel_request")] cancel_request: CANCEL_REQUEST_METHOD_NAME, }; @@ -95,25 +87,19 @@ pub(crate) const CANCEL_REQUEST_METHOD_NAME: &str = "$/cancel_request"; #[schemars(inline)] #[non_exhaustive] pub enum ProtocolLevelNotification { - /// **UNSTABLE** - /// - /// This capability is not part of the spec yet, and may be removed or - /// changed at any point. - /// /// Cancels an ongoing request. /// /// This is a notification sent by the side that sent a request to cancel that request. /// /// Upon receiving this notification, the receiver: /// - /// 1. MUST cancel the corresponding request activity and all nested activities + /// 1. MAY cancel the corresponding request activity and all nested activities /// 2. MAY send any pending notifications. /// 3. MUST send one of these responses for the original request: /// - Valid response with appropriate data (partial results or cancellation marker) /// - Error response with code `-32800` (Cancelled) /// /// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation) - #[cfg(feature = "unstable_cancel_request")] CancelRequestNotification(CancelRequestNotification), } @@ -122,7 +108,6 @@ impl ProtocolLevelNotification { #[must_use] pub fn method(&self) -> &str { match self { - #[cfg(feature = "unstable_cancel_request")] Self::CancelRequestNotification(..) => PROTOCOL_LEVEL_METHOD_NAMES.cancel_request, } } diff --git a/docs/docs.json b/docs/docs.json index a78bb83d6..cdf4cf97b 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -77,6 +77,7 @@ "protocol/v1/content", "protocol/v1/tool-calls", "protocol/v1/file-system", + "protocol/v1/cancellation", "protocol/v1/terminals", "protocol/v1/agent-plan", "protocol/v1/session-modes", @@ -126,6 +127,7 @@ "protocol/v2/prompt-lifecycle", "protocol/v2/content", "protocol/v2/tool-calls", + "protocol/v2/cancellation", "protocol/v2/agent-plan", "protocol/v2/session-config-options", "protocol/v2/slash-commands", @@ -209,7 +211,7 @@ }, { "group": "Preview", - "pages": ["rfds/request-cancellation"] + "pages": [] }, { "group": "Completed", @@ -228,7 +230,8 @@ "rfds/session-usage", "rfds/session-delete", "rfds/model-config-category", - "rfds/rust-sdk-v1" + "rfds/rust-sdk-v1", + "rfds/request-cancellation" ] } ] diff --git a/docs/protocol/v1/cancellation.mdx b/docs/protocol/v1/cancellation.mdx new file mode 100644 index 000000000..d5ce022bf --- /dev/null +++ b/docs/protocol/v1/cancellation.mdx @@ -0,0 +1,68 @@ +--- +title: "Cancellation" +description: "Mechanisms for request cancellation" +--- + +ACP uses JSON-RPC 2.0 for making requests and getting responses. + +The JSON-RPC specification doesn't define any standard mechanism for request cancellation and keeps it up to the implementation. + +## `$/cancel_request` Notification + +In order to provide a consistent approach to cancellation, ACP defines a `$/cancel_request` notification that can be sent to cancel requests. + +Cancellation remains optional as it might not be implementable in all clients or servers. For example if the implementation uses a single threaded synchronous programming language then there is little it can do to react to a `$/cancel_request` notification. + +When a `$/cancel_request` notification is received by a supporting implementation, the implementation: + +- **MAY** cancel the corresponding request activity and all nested activities related to that request +- **MAY** finish sending any pending notifications before responding +- **MUST** send one of these responses for the original request: + - A valid response with appropriate data (such as partial results or cancellation marker) + - An error response with code [`-32800` (Request Cancelled)](/protocol/v1/schema#errorcode) + +The calling side **MAY** implement graceful cancellation processing by waiting for the response from the remote side. + +Cancellation **MAY** also be done explicitly on a per-feature basis within the protocol to cover specific scenarios, such as cancellation of a [prompt turn](/protocol/v1/prompt-turn#cancellation). + +## Internal Cancellation + +Requests can also be cancelled internally by the executing party without receiving `$/cancel_request`: + +- **Client-side examples**: User closes IDE, switches to different project, file becomes unavailable +- **Agent-side examples**: LLM context limit reached, internal timeout, resource constraints + +When internal cancellation occurs, the executing party **SHOULD**: + +- Send the same `-32800` (Cancelled) error response as if `$/cancel_request` was received +- Ensure consistent behavior regardless of cancellation source + +## Example: Cascading Cancellation Flow + +```mermaid +sequenceDiagram + participant Client + participant Agent + + Note over Client,Agent: 1. Session prompt in progress + Client->>Agent: session/prompt (id=1, "Analyze file X") + Agent-->>Client: session/update (agent started processing) + + Note over Client,Agent: 2. Agent makes concurrent requests + Agent->>Client: terminal/create (id=2, "grep pattern file.txt") + Agent->>Client: session/request_permission (id=3, "read sensitive file") + + Note over Client,Agent: 3. Client cancels the prompt turn + Client->>Agent: session/cancel (sessionId) + + Note over Client,Agent: 4. Agent cascades cancellation internally + Agent->>Client: $/cancel_request (id=2) [terminal request] + Agent->>Client: $/cancel_request (id=3) [permission request] + + Note over Client,Agent: 5. Client confirms individual cancellations + Client->>Agent: response to id=2 (error -32800 "Cancelled") + Client->>Agent: response to id=3 (error -32800 "Cancelled") + + Note over Client,Agent: 6. Agent completes prompt cancellation + Agent->>Client: response to id=1 (stopReason: "cancelled") +``` diff --git a/docs/protocol/v1/draft/cancellation.mdx b/docs/protocol/v1/draft/cancellation.mdx index ecf25df73..0a0117b85 100644 --- a/docs/protocol/v1/draft/cancellation.mdx +++ b/docs/protocol/v1/draft/cancellation.mdx @@ -15,7 +15,7 @@ Cancellation will remain optional as it might not be implementable in all client When a `$/cancel_request` notification is received by a supporting implementation, the implementation: -- **MUST** cancel the corresponding request activity and all nested activities related to that request +- **MAY** cancel the corresponding request activity and all nested activities related to that request - **MAY** finish sending any pending notifications before responding - **MUST** send one of these responses for the original request: - A valid response with appropriate data (such as partial results or cancellation marker) @@ -32,7 +32,7 @@ Requests can also be cancelled internally by the executing party without receivi - **Client-side examples**: User closes IDE, switches to different project, file becomes unavailable - **Agent-side examples**: LLM context limit reached, internal timeout, resource constraints -When internal cancellation occurs, the executing party **MUST**: +When internal cancellation occurs, the executing party **SHOULD**: - Send the same `-32800` (Cancelled) error response as if `$/cancel_request` was received - Ensure consistent behavior regardless of cancellation source diff --git a/docs/protocol/v1/draft/schema.mdx b/docs/protocol/v1/draft/schema.mdx index 93027d567..c79671aee 100644 --- a/docs/protocol/v1/draft/schema.mdx +++ b/docs/protocol/v1/draft/schema.mdx @@ -2567,18 +2567,13 @@ starting with '$/' it is free to ignore the notification. ### $/cancel_request -**UNSTABLE** - -This capability is not part of the spec yet, and may be removed or -changed at any point. - Cancels an ongoing request. This is a notification sent by the side that sent a request to cancel that request. Upon receiving this notification, the receiver: -1. MUST cancel the corresponding request activity and all nested activities +1. MAY cancel the corresponding request activity and all nested activities 2. MAY send any pending notifications. 3. MUST send one of these responses for the original request: @@ -2589,10 +2584,6 @@ See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v1/dr #### CancelRequestNotification -**UNSTABLE** - -This capability is not part of the spec yet, and may be removed or changed at any point. - Notification to cancel an ongoing request. See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v1/draft/cancellation) @@ -4456,13 +4447,9 @@ and use the reserved range (-32000 to -32099) for protocol-specific errors. -**Request cancelled**: **UNSTABLE** - -This capability is not part of the spec yet, and may be removed or changed at any point. - -Execution of the method was aborted either due to a cancellation request from the caller or -because of resource constraints or shutdown. - + **Request cancelled**: Execution of the method was aborted either due to a + cancellation request from the caller or because of resource constraints or + shutdown. diff --git a/docs/protocol/v1/schema.mdx b/docs/protocol/v1/schema.mdx index 65b4a2ed3..849acf878 100644 --- a/docs/protocol/v1/schema.mdx +++ b/docs/protocol/v1/schema.mdx @@ -1373,6 +1373,57 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/e The signal that terminated the process (may be null if exited normally). +## Protocol Level + +Defines the interface that ACP-compliant agents and clients must both implement. + +Notifications whose methods start with '$/' are messages which are protocol +implementation dependent and might not be implementable in all clients or +agents. For example if the implementation uses a single threaded synchronous +programming language then there is little it can do to react to a +`$/cancel_request` notification. If an agent or client receives notifications +starting with '$/' it is free to ignore the notification. + + +### $/cancel_request + +Cancels an ongoing request. + +This is a notification sent by the side that sent a request to cancel that request. + +Upon receiving this notification, the receiver: + +1. MAY cancel the corresponding request activity and all nested activities +2. MAY send any pending notifications. +3. MUST send one of these responses for the original request: + +- Valid response with appropriate data (partial results or cancellation marker) +- Error response with code `-32800` (Cancelled) + +See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v1/cancellation) + +#### CancelRequestNotification + +Notification to cancel an ongoing request. + +See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v1/cancellation) + +**Type:** Object + +**Properties:** + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Implementations MUST NOT make assumptions about values at +these keys. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/extensibility) + + +RequestId} required> + The ID of the request to cancel. + + ## AgentAuthCapabilities Authentication-related capabilities supported by the agent. @@ -2187,6 +2238,12 @@ and use the reserved range (-32000 to -32099) for protocol-specific errors. implementation-defined server errors. + + **Request cancelled**: Execution of the method was aborted either due to a + cancellation request from the caller or because of resource constraints or + shutdown. + + **Authentication required**: Authentication is required before this operation can be performed. diff --git a/docs/protocol/v2/cancellation.mdx b/docs/protocol/v2/cancellation.mdx new file mode 100644 index 000000000..00795cbfb --- /dev/null +++ b/docs/protocol/v2/cancellation.mdx @@ -0,0 +1,69 @@ +--- +title: "Cancellation" +description: "Mechanisms for request cancellation" +--- + +ACP uses JSON-RPC 2.0 for making requests and getting responses. + +The JSON-RPC specification doesn't define any standard mechanism for request cancellation and keeps it up to the implementation. + +## `$/cancel_request` Notification + +In order to provide a consistent approach to cancellation, ACP defines a `$/cancel_request` notification that can be sent to cancel requests. + +Cancellation remains optional as it might not be implementable in all clients or servers. For example if the implementation uses a single threaded synchronous programming language then there is little it can do to react to a `$/cancel_request` notification. + +When a `$/cancel_request` notification is received by a supporting implementation, the implementation: + +- **MAY** cancel the corresponding request activity and all nested activities related to that request +- **MAY** finish sending any pending notifications before responding +- **MUST** send one of these responses for the original request: + - A valid response with appropriate data (such as partial results or cancellation marker) + - An error response with code [`-32800` (Request Cancelled)](/protocol/v2/schema#errorcode) + +The calling side **MAY** implement graceful cancellation processing by waiting for the response from the remote side. + +Cancellation **MAY** also be done explicitly on a per-feature basis within the protocol to cover specific scenarios, such as cancellation of [active session work](/protocol/v2/prompt-lifecycle#cancellation). + +## Internal Cancellation + +Requests can also be cancelled internally by the executing party without receiving `$/cancel_request`: + +- **Client-side examples**: User closes IDE, switches to different project, file becomes unavailable +- **Agent-side examples**: LLM context limit reached, internal timeout, resource constraints + +When internal cancellation occurs, the executing party **SHOULD**: + +- Send the same `-32800` (Cancelled) error response as if `$/cancel_request` was received +- Ensure consistent behavior regardless of cancellation source + +## Example: Cascading Cancellation Flow + +```mermaid +sequenceDiagram + participant Client + participant Agent + + Note over Client,Agent: 1. Session prompt in progress + Client->>Agent: session/prompt (id=1, "Analyze file X") + Agent-->>Client: response to id=1 ({}) + Agent->>Client: session/update (state_update: running) + + Note over Client,Agent: 2. Agent makes concurrent permission requests + Agent->>Client: session/request_permission (id=2, "read sensitive file") + Agent->>Client: session/request_permission (id=3, "apply workspace changes") + + Note over Client,Agent: 3. Client cancels active session work + Client->>Agent: session/cancel (sessionId) + + Note over Client,Agent: 4. Agent cascades cancellation internally + Agent->>Client: $/cancel_request (id=2) [permission request] + Agent->>Client: $/cancel_request (id=3) [permission request] + + Note over Client,Agent: 5. Client confirms individual cancellations + Client->>Agent: response to id=2 (error -32800 "Cancelled") + Client->>Agent: response to id=3 (error -32800 "Cancelled") + + Note over Client,Agent: 6. Agent reports cancellation completion + Agent->>Client: session/update (state_update: idle, stopReason: "cancelled") +``` diff --git a/docs/protocol/v2/draft/cancellation.mdx b/docs/protocol/v2/draft/cancellation.mdx index 5f0cca79f..463aa3bab 100644 --- a/docs/protocol/v2/draft/cancellation.mdx +++ b/docs/protocol/v2/draft/cancellation.mdx @@ -15,7 +15,7 @@ Cancellation will remain optional as it might not be implementable in all client When a `$/cancel_request` notification is received by a supporting implementation, the implementation: -- **MUST** cancel the corresponding request activity and all nested activities related to that request +- **MAY** cancel the corresponding request activity and all nested activities related to that request - **MAY** finish sending any pending notifications before responding - **MUST** send one of these responses for the original request: - A valid response with appropriate data (such as partial results or cancellation marker) @@ -32,7 +32,7 @@ Requests can also be cancelled internally by the executing party without receivi - **Client-side examples**: User closes IDE, switches to different project, file becomes unavailable - **Agent-side examples**: LLM context limit reached, internal timeout, resource constraints -When internal cancellation occurs, the executing party **MUST**: +When internal cancellation occurs, the executing party **SHOULD**: - Send the same `-32800` (Cancelled) error response as if `$/cancel_request` was received - Ensure consistent behavior regardless of cancellation source diff --git a/docs/protocol/v2/draft/schema.mdx b/docs/protocol/v2/draft/schema.mdx index 30c691b61..7437aabe7 100644 --- a/docs/protocol/v2/draft/schema.mdx +++ b/docs/protocol/v2/draft/schema.mdx @@ -2046,18 +2046,13 @@ starting with '$/' it is free to ignore the notification. ### $/cancel_request -**UNSTABLE** - -This capability is not part of the spec yet, and may be removed or -changed at any point. - Cancels an ongoing request. This is a notification sent by the side that sent a request to cancel that request. Upon receiving this notification, the receiver: -1. MUST cancel the corresponding request activity and all nested activities +1. MAY cancel the corresponding request activity and all nested activities 2. MAY send any pending notifications. 3. MUST send one of these responses for the original request: @@ -2068,10 +2063,6 @@ See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/dr #### CancelRequestNotification -**UNSTABLE** - -This capability is not part of the spec yet, and may be removed or changed at any point. - Notification to cancel an ongoing request. See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/draft/cancellation) @@ -3973,13 +3964,9 @@ and use the reserved range (-32000 to -32099) for protocol-specific errors. -**Request cancelled**: **UNSTABLE** - -This capability is not part of the spec yet, and may be removed or changed at any point. - -Execution of the method was aborted either due to a cancellation request from the caller or -because of resource constraints or shutdown. - + **Request cancelled**: Execution of the method was aborted either due to a + cancellation request from the caller or because of resource constraints or + shutdown. diff --git a/docs/protocol/v2/schema.mdx b/docs/protocol/v2/schema.mdx index 8ef59f4ab..e845fdc6a 100644 --- a/docs/protocol/v2/schema.mdx +++ b/docs/protocol/v2/schema.mdx @@ -866,6 +866,57 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e The actual update content. +## Protocol Level + +Defines the interface that ACP-compliant agents and clients must both implement. + +Notifications whose methods start with '$/' are messages which are protocol +implementation dependent and might not be implementable in all clients or +agents. For example if the implementation uses a single threaded synchronous +programming language then there is little it can do to react to a +`$/cancel_request` notification. If an agent or client receives notifications +starting with '$/' it is free to ignore the notification. + + +### $/cancel_request + +Cancels an ongoing request. + +This is a notification sent by the side that sent a request to cancel that request. + +Upon receiving this notification, the receiver: + +1. MAY cancel the corresponding request activity and all nested activities +2. MAY send any pending notifications. +3. MUST send one of these responses for the original request: + +- Valid response with appropriate data (partial results or cancellation marker) +- Error response with code `-32800` (Cancelled) + +See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/cancellation) + +#### CancelRequestNotification + +Notification to cancel an ongoing request. + +See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/cancellation) + +**Type:** Object + +**Properties:** + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Implementations MUST NOT make assumptions about values at +these keys. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) + + +RequestId} required> + The ID of the request to cancel. + + ## AgentAuthCapabilities Authentication-related capabilities supported by the agent. @@ -1795,6 +1846,12 @@ and use the reserved range (-32000 to -32099) for protocol-specific errors. implementation-defined server errors. + + **Request cancelled**: Execution of the method was aborted either due to a + cancellation request from the caller or because of resource constraints or + shutdown. + + **Authentication required**: Authentication is required before this operation can be performed. diff --git a/docs/rfds/request-cancellation.mdx b/docs/rfds/request-cancellation.mdx index 95539db1a..a73762998 100644 --- a/docs/rfds/request-cancellation.mdx +++ b/docs/rfds/request-cancellation.mdx @@ -107,7 +107,7 @@ Add standard JSON-RPC error code `-32800` for cancelled requests: | `agentclientprotocol/rust-sdk` | [agentclientprotocol/rust-sdk#179](https://github.com/agentclientprotocol/rust-sdk/pull/179) | Merged | | `agentclientprotocol/typescript-sdk` | [agentclientprotocol/typescript-sdk#195](https://github.com/agentclientprotocol/typescript-sdk/pull/195) | Merged | | `agentclientprotocol/claude-agent-acp` | [agentclientprotocol/claude-agent-acp#801](https://github.com/agentclientprotocol/claude-agent-acp/pull/801) | Merged | -| `agentclientprotocol/codex-acp` | [agentclientprotocol/codex-acp#221](https://github.com/agentclientprotocol/codex-acp/pull/221) | Open | +| `agentclientprotocol/codex-acp` | [agentclientprotocol/codex-acp#221](https://github.com/agentclientprotocol/codex-acp/pull/221) | Merged | | `agentclientprotocol/kotlin-sdk` | [agentclientprotocol/kotlin-sdk@f345883](https://github.com/agentclientprotocol/kotlin-sdk/commit/f3458831da628e26ee29c4a5834d55b443bf5a31) | Needs method name update | ## Frequently asked questions @@ -202,7 +202,8 @@ This ensures complete cleanup and prevents resource leaks. ## Revision history -- 2025-11-13: Initial version converted from PR #183 -- 2025-12-05: Updated with current implementation. -- 2025-12-09: Mirror LSP behavior. +- 2026-06-29: Moved to Completed and stabilized request cancellation in the protocol artifacts. - 2026-06-24: Move to Preview stage +- 2025-12-09: Mirror LSP behavior. +- 2025-12-05: Updated with current implementation. +- 2025-11-13: Initial version converted from PR #183 diff --git a/docs/rfds/updates.mdx b/docs/rfds/updates.mdx index ebfee6f62..0286139dc 100644 --- a/docs/rfds/updates.mdx +++ b/docs/rfds/updates.mdx @@ -6,6 +6,13 @@ rss: true This page tracks lifecycle changes for ACP Requests for Dialog. For broader ACP announcements, see [Updates](/updates). + +## Request Cancellation RFD moves to Completed + +The RFD for `$/cancel_request` protocol-level request cancellation has been stabilized and is now part of the protocol. Either side can send this notification to request cancellation of an outstanding JSON-RPC request by ID. Please review the [documentation](/protocol/v1/cancellation) for more information. + + + ## Rust SDK based on SACP RFD moves to Completed diff --git a/schema-generator/Cargo.toml b/schema-generator/Cargo.toml index 48c492863..ec224ed36 100644 --- a/schema-generator/Cargo.toml +++ b/schema-generator/Cargo.toml @@ -11,12 +11,8 @@ repository = "https://github.com/agentclientprotocol/agent-client-protocol" workspace = true [features] -unstable = [ - "agent-client-protocol-schema/unstable", - "unstable_cancel_request", -] +unstable = ["agent-client-protocol-schema/unstable"] unstable_protocol_v2 = ["agent-client-protocol-schema/unstable_protocol_v2"] -unstable_cancel_request = ["agent-client-protocol-schema/unstable_cancel_request"] [dependencies] agent-client-protocol-schema = { workspace = true } diff --git a/schema-generator/src/main.rs b/schema-generator/src/main.rs index 51ea31d5a..2ac58dc34 100644 --- a/schema-generator/src/main.rs +++ b/schema-generator/src/main.rs @@ -4,22 +4,15 @@ use agent_client_protocol_schema::ProtocolVersion; #[cfg(not(feature = "unstable_protocol_v2"))] use agent_client_protocol_schema::v1::{ AGENT_METHOD_NAMES, AgentNotification, AgentRequest, AgentResponse, CLIENT_METHOD_NAMES, - ClientNotification, ClientRequest, ClientResponse, JsonRpcMessage, Notification, Request, - Response, + ClientNotification, ClientRequest, ClientResponse, JsonRpcMessage, Notification, + PROTOCOL_LEVEL_METHOD_NAMES, ProtocolLevelNotification, Request, Response, }; -#[cfg(all( - feature = "unstable_cancel_request", - not(feature = "unstable_protocol_v2") -))] -use agent_client_protocol_schema::v1::{PROTOCOL_LEVEL_METHOD_NAMES, ProtocolLevelNotification}; #[cfg(feature = "unstable_protocol_v2")] use agent_client_protocol_schema::v2::{ AGENT_METHOD_NAMES, AgentNotification, AgentRequest, AgentResponse, CLIENT_METHOD_NAMES, ClientNotification, ClientRequest, ClientResponse, JsonRpcBatch, JsonRpcMessage, Notification, - Request, Response, + PROTOCOL_LEVEL_METHOD_NAMES, ProtocolLevelNotification, Request, Response, }; -#[cfg(all(feature = "unstable_cancel_request", feature = "unstable_protocol_v2"))] -use agent_client_protocol_schema::v2::{PROTOCOL_LEVEL_METHOD_NAMES, ProtocolLevelNotification}; use schemars::{ JsonSchema, generate::SchemaSettings, @@ -86,7 +79,6 @@ enum ClientOutgoingMessage { enum AgentBatchCallMessage { Request(Request), Notification(Notification), - #[cfg(feature = "unstable_cancel_request")] ProtocolLevelNotification(Notification), } @@ -99,7 +91,6 @@ enum AgentBatchCallMessage { enum ClientBatchCallMessage { Request(Request), Notification(Notification), - #[cfg(feature = "unstable_cancel_request")] ProtocolLevelNotification(Notification), } @@ -119,7 +110,6 @@ enum AcpTypes { ClientBatchCall(JsonRpcBatch), #[cfg(feature = "unstable_protocol_v2")] ClientBatchResponse(JsonRpcBatch>), - #[cfg(feature = "unstable_cancel_request")] ProtocolLevel(JsonRpcMessage>), } @@ -206,13 +196,6 @@ fn write_schema(schema_value: &serde_json::Value, schema_dir: &Path, docs_protoc let schema_protocol_version = ProtocolVersion::V1; // Create a combined metadata object - #[cfg(not(feature = "unstable_cancel_request"))] - let metadata = serde_json::json!({ - "version": schema_protocol_version, - "agentMethods": AGENT_METHOD_NAMES, - "clientMethods": CLIENT_METHOD_NAMES, - }); - #[cfg(feature = "unstable_cancel_request")] let metadata = serde_json::json!({ "version": schema_protocol_version, "agentMethods": AGENT_METHOD_NAMES, @@ -403,7 +386,6 @@ mod schema_annotation_tests { ); } - #[cfg(feature = "unstable_cancel_request")] for title in ["AgentBatchCall", "ClientBatchCall"] { let batch_schema = root_variant_schema(&schema, title); assert!( @@ -412,7 +394,6 @@ mod schema_annotation_tests { ); } - #[cfg(feature = "unstable_cancel_request")] { let protocol_level = root_variant_schema(&schema, "ProtocolLevel"); assert_eq!( @@ -799,7 +780,7 @@ mod schema_annotation_tests { ); } - #[cfg(all(feature = "unstable_protocol_v2", feature = "unstable_cancel_request"))] + #[cfg(feature = "unstable_protocol_v2")] fn schema_contains_ref(schema: &Value, ref_path: &str) -> bool { match schema { Value::Object(object) => object.iter().any(|(key, value)| { @@ -971,7 +952,6 @@ and control access to resources." types, ); } - #[cfg(feature = "unstable_cancel_request")] { writeln!(&mut self.output, "## Protocol Level").unwrap(); writeln!(&mut self.output).unwrap(); @@ -1936,7 +1916,6 @@ starting with '$/' it is free to ignore the notification." } } - #[cfg(feature = "unstable_cancel_request")] fn protocol_method_doc(&self, method_name: &str) -> &String { match method_name { "$/cancel_request" => self.protocol.get("CancelRequestNotification").unwrap(), diff --git a/schema/v1/meta.json b/schema/v1/meta.json index 9281f19f3..670d27876 100644 --- a/schema/v1/meta.json +++ b/schema/v1/meta.json @@ -25,5 +25,8 @@ "terminal_release": "terminal/release", "terminal_wait_for_exit": "terminal/wait_for_exit", "terminal_kill": "terminal/kill" + }, + "protocolMethods": { + "cancel_request": "$/cancel_request" } } diff --git a/schema/v1/schema.json b/schema/v1/schema.json index 6d1baa89c..e7461b663 100644 --- a/schema/v1/schema.json +++ b/schema/v1/schema.json @@ -77,6 +77,45 @@ ] } ] + }, + { + "title": "ProtocolLevel", + "description": "A message (request, response, or notification) with `\"jsonrpc\": \"2.0\"` specified as\n[required by JSON-RPC 2.0 Specification][1].\n\n[1]: https://www.jsonrpc.org/specification#compatibility", + "type": "object", + "properties": { + "jsonrpc": { + "type": "string", + "enum": ["2.0"] + }, + "method": { + "description": "The notification method name.", + "type": "string" + }, + "params": { + "description": "Method-specific notification parameters.", + "anyOf": [ + { + "description": "General protocol-level notifications that all sides are expected to\nimplement.\n\nNotifications whose methods start with '$/' are messages which\nare protocol implementation dependent and might not be implementable in all\nclients or agents. For example if the implementation uses a single threaded\nsynchronous programming language then there is little it can do to react to\na `$/cancel_request` notification. If an agent or client receives\nnotifications starting with '$/' it is free to ignore the notification.\n\nNotifications do not expect a response.", + "anyOf": [ + { + "title": "CancelRequestNotification", + "description": "Cancels an ongoing request.\n\nThis is a notification sent by the side that sent a request to cancel that request.\n\nUpon receiving this notification, the receiver:\n\n1. MAY cancel the corresponding request activity and all nested activities\n2. MAY send any pending notifications.\n3. MUST send one of these responses for the original request:\n - Valid response with appropriate data (partial results or cancellation marker)\n - Error response with code `-32800` (Cancelled)\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation)", + "allOf": [ + { + "$ref": "#/$defs/CancelRequestNotification" + } + ] + } + ] + }, + { + "type": "null" + } + ] + } + }, + "required": ["jsonrpc", "method"], + "x-docs-ignore": true } ], "$defs": { @@ -2586,6 +2625,13 @@ "format": "int32", "const": -32603 }, + { + "title": "Request cancelled", + "description": "**Request cancelled**: Execution of the method was aborted either due to a cancellation request from the caller or\nbecause of resource constraints or shutdown.", + "type": "integer", + "format": "int32", + "const": -32800 + }, { "title": "Authentication required", "description": "**Authentication required**: Authentication is required before this operation can be performed.", @@ -4483,6 +4529,29 @@ "required": ["sessionId"], "x-side": "agent", "x-method": "session/cancel" + }, + "CancelRequestNotification": { + "description": "Notification to cancel an ongoing request.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation)", + "type": "object", + "properties": { + "requestId": { + "description": "The ID of the request to cancel.", + "allOf": [ + { + "$ref": "#/$defs/RequestId" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": ["requestId"], + "x-side": "protocol", + "x-method": "$/cancel_request" } } } diff --git a/schema/v1/schema.unstable.json b/schema/v1/schema.unstable.json index cd608976e..3f46791fe 100644 --- a/schema/v1/schema.unstable.json +++ b/schema/v1/schema.unstable.json @@ -99,7 +99,7 @@ "anyOf": [ { "title": "CancelRequestNotification", - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or\nchanged at any point.\n\nCancels an ongoing request.\n\nThis is a notification sent by the side that sent a request to cancel that request.\n\nUpon receiving this notification, the receiver:\n\n1. MUST cancel the corresponding request activity and all nested activities\n2. MAY send any pending notifications.\n3. MUST send one of these responses for the original request:\n - Valid response with appropriate data (partial results or cancellation marker)\n - Error response with code `-32800` (Cancelled)\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation)", + "description": "Cancels an ongoing request.\n\nThis is a notification sent by the side that sent a request to cancel that request.\n\nUpon receiving this notification, the receiver:\n\n1. MAY cancel the corresponding request activity and all nested activities\n2. MAY send any pending notifications.\n3. MUST send one of these responses for the original request:\n - Valid response with appropriate data (partial results or cancellation marker)\n - Error response with code `-32800` (Cancelled)\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation)", "allOf": [ { "$ref": "#/$defs/CancelRequestNotification" @@ -4809,7 +4809,7 @@ }, { "title": "Request cancelled", - "description": "**Request cancelled**: **UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nExecution of the method was aborted either due to a cancellation request from the caller or\nbecause of resource constraints or shutdown.", + "description": "**Request cancelled**: Execution of the method was aborted either due to a cancellation request from the caller or\nbecause of resource constraints or shutdown.", "type": "integer", "format": "int32", "const": -32800 @@ -8628,7 +8628,7 @@ ] }, "CancelRequestNotification": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nNotification to cancel an ongoing request.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation)", + "description": "Notification to cancel an ongoing request.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation)", "type": "object", "properties": { "requestId": { diff --git a/schema/v2/meta.json b/schema/v2/meta.json index e1ecdb25a..1b42e980e 100644 --- a/schema/v2/meta.json +++ b/schema/v2/meta.json @@ -17,5 +17,8 @@ "clientMethods": { "session_request_permission": "session/request_permission", "session_update": "session/update" + }, + "protocolMethods": { + "cancel_request": "$/cancel_request" } } diff --git a/schema/v2/schema.json b/schema/v2/schema.json index b64fae566..1d2cab661 100644 --- a/schema/v2/schema.json +++ b/schema/v2/schema.json @@ -108,6 +108,14 @@ "$ref": "#/$defs/AgentNotification" } ] + }, + { + "title": "ProtocolLevelNotification", + "allOf": [ + { + "$ref": "#/$defs/ProtocolLevelNotification" + } + ] } ] }, @@ -316,6 +324,14 @@ "$ref": "#/$defs/ClientNotification" } ] + }, + { + "title": "ProtocolLevelNotification", + "allOf": [ + { + "$ref": "#/$defs/ProtocolLevelNotification" + } + ] } ] }, @@ -403,6 +419,45 @@ "x-docs-ignore": true }, "minItems": 1 + }, + { + "title": "ProtocolLevel", + "description": "A message (request, response, or notification) with `\"jsonrpc\": \"2.0\"` specified as\n[required by JSON-RPC 2.0 Specification][1].\n\n[1]: https://www.jsonrpc.org/specification#compatibility", + "type": "object", + "properties": { + "jsonrpc": { + "type": "string", + "enum": ["2.0"] + }, + "method": { + "description": "The notification method name.", + "type": "string" + }, + "params": { + "description": "Method-specific notification parameters.", + "anyOf": [ + { + "description": "General protocol-level notifications that all sides are expected to\nimplement.\n\nNotifications whose methods start with '$/' are messages which\nare protocol implementation dependent and might not be implementable in all\nclients or agents. For example if the implementation uses a single threaded\nsynchronous programming language then there is little it can do to react to\na `$/cancel_request` notification. If an agent or client receives\nnotifications starting with '$/' it is free to ignore the notification.\n\nNotifications do not expect a response.", + "anyOf": [ + { + "title": "CancelRequestNotification", + "description": "Cancels an ongoing request.\n\nThis is a notification sent by the side that sent a request to cancel that request.\n\nUpon receiving this notification, the receiver:\n\n1. MAY cancel the corresponding request activity and all nested activities\n2. MAY send any pending notifications.\n3. MUST send one of these responses for the original request:\n - Valid response with appropriate data (partial results or cancellation marker)\n - Error response with code `-32800` (Cancelled)\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/cancellation)", + "allOf": [ + { + "$ref": "#/$defs/CancelRequestNotification" + } + ] + } + ] + }, + { + "type": "null" + } + ] + } + }, + "required": ["jsonrpc", "method"], + "x-docs-ignore": true } ], "$defs": { @@ -2648,6 +2703,13 @@ "format": "int32", "const": -32603 }, + { + "title": "Request cancelled", + "description": "**Request cancelled**: Execution of the method was aborted either due to a cancellation request from the caller or\nbecause of resource constraints or shutdown.", + "type": "integer", + "format": "int32", + "const": -32800 + }, { "title": "Authentication required", "description": "**Authentication required**: Authentication is required before this operation can be performed.", @@ -4797,6 +4859,63 @@ "required": ["sessionId"], "x-side": "agent", "x-method": "session/cancel" + }, + "ProtocolLevelNotification": { + "description": "A JSON-RPC notification object.", + "type": "object", + "properties": { + "method": { + "description": "The notification method name.", + "type": "string" + }, + "params": { + "description": "Method-specific notification parameters.", + "anyOf": [ + { + "description": "General protocol-level notifications that all sides are expected to\nimplement.\n\nNotifications whose methods start with '$/' are messages which\nare protocol implementation dependent and might not be implementable in all\nclients or agents. For example if the implementation uses a single threaded\nsynchronous programming language then there is little it can do to react to\na `$/cancel_request` notification. If an agent or client receives\nnotifications starting with '$/' it is free to ignore the notification.\n\nNotifications do not expect a response.", + "anyOf": [ + { + "title": "CancelRequestNotification", + "description": "Cancels an ongoing request.\n\nThis is a notification sent by the side that sent a request to cancel that request.\n\nUpon receiving this notification, the receiver:\n\n1. MAY cancel the corresponding request activity and all nested activities\n2. MAY send any pending notifications.\n3. MUST send one of these responses for the original request:\n - Valid response with appropriate data (partial results or cancellation marker)\n - Error response with code `-32800` (Cancelled)\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/cancellation)", + "allOf": [ + { + "$ref": "#/$defs/CancelRequestNotification" + } + ] + } + ] + }, + { + "type": "null" + } + ] + } + }, + "required": ["method"], + "x-docs-ignore": true + }, + "CancelRequestNotification": { + "description": "Notification to cancel an ongoing request.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/cancellation)", + "type": "object", + "properties": { + "requestId": { + "description": "The ID of the request to cancel.", + "allOf": [ + { + "$ref": "#/$defs/RequestId" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": ["requestId"], + "x-side": "protocol", + "x-method": "$/cancel_request" } } } diff --git a/schema/v2/schema.unstable.json b/schema/v2/schema.unstable.json index 60cdcb14a..3a8f7aea1 100644 --- a/schema/v2/schema.unstable.json +++ b/schema/v2/schema.unstable.json @@ -549,7 +549,7 @@ "anyOf": [ { "title": "CancelRequestNotification", - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or\nchanged at any point.\n\nCancels an ongoing request.\n\nThis is a notification sent by the side that sent a request to cancel that request.\n\nUpon receiving this notification, the receiver:\n\n1. MUST cancel the corresponding request activity and all nested activities\n2. MAY send any pending notifications.\n3. MUST send one of these responses for the original request:\n - Valid response with appropriate data (partial results or cancellation marker)\n - Error response with code `-32800` (Cancelled)\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/draft/cancellation)", + "description": "Cancels an ongoing request.\n\nThis is a notification sent by the side that sent a request to cancel that request.\n\nUpon receiving this notification, the receiver:\n\n1. MAY cancel the corresponding request activity and all nested activities\n2. MAY send any pending notifications.\n3. MUST send one of these responses for the original request:\n - Valid response with appropriate data (partial results or cancellation marker)\n - Error response with code `-32800` (Cancelled)\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/draft/cancellation)", "allOf": [ { "$ref": "#/$defs/CancelRequestNotification" @@ -5049,7 +5049,7 @@ }, { "title": "Request cancelled", - "description": "**Request cancelled**: **UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nExecution of the method was aborted either due to a cancellation request from the caller or\nbecause of resource constraints or shutdown.", + "description": "**Request cancelled**: Execution of the method was aborted either due to a cancellation request from the caller or\nbecause of resource constraints or shutdown.", "type": "integer", "format": "int32", "const": -32800 @@ -9037,7 +9037,7 @@ "anyOf": [ { "title": "CancelRequestNotification", - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or\nchanged at any point.\n\nCancels an ongoing request.\n\nThis is a notification sent by the side that sent a request to cancel that request.\n\nUpon receiving this notification, the receiver:\n\n1. MUST cancel the corresponding request activity and all nested activities\n2. MAY send any pending notifications.\n3. MUST send one of these responses for the original request:\n - Valid response with appropriate data (partial results or cancellation marker)\n - Error response with code `-32800` (Cancelled)\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/draft/cancellation)", + "description": "Cancels an ongoing request.\n\nThis is a notification sent by the side that sent a request to cancel that request.\n\nUpon receiving this notification, the receiver:\n\n1. MAY cancel the corresponding request activity and all nested activities\n2. MAY send any pending notifications.\n3. MUST send one of these responses for the original request:\n - Valid response with appropriate data (partial results or cancellation marker)\n - Error response with code `-32800` (Cancelled)\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/draft/cancellation)", "allOf": [ { "$ref": "#/$defs/CancelRequestNotification" @@ -9056,7 +9056,7 @@ "x-docs-ignore": true }, "CancelRequestNotification": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nNotification to cancel an ongoing request.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/draft/cancellation)", + "description": "Notification to cancel an ongoing request.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/draft/cancellation)", "type": "object", "properties": { "requestId": {