Ext methods and notifications

Author: agu-z

docs/protocol/schema.mdx

@@ -1016,6 +1016,48 @@ An environment variable to set when launching an MCP server.
   The value to set for the environment variable.
 </ResponseField>
 
+## <span class="font-mono">ExtMethodRequest</span>
+
+Request parameters for extension method calls.
+
+**Type:** Object
+
+**Properties:**
+
+<ResponseField name="method" type={"string"} required>
+  The identifier for the extension method.
+
+To help avoid conflicts, it's a good practice to prefix extension
+methods with a unique identifier such as domain name.
+
+</ResponseField>
+<ResponseField name="params" type={"object"} required>
+  The parameters for the extension method, can be any JSON value.
+</ResponseField>
+
+## <span class="font-mono">ExtMethodResponse</span>
+
+Response from extension method calls.
+
+## <span class="font-mono">ExtNotification</span>
+
+Extension notification parameters
+
+**Type:** Object
+
+**Properties:**
+
+<ResponseField name="method" type={"string"} required>
+  The identifier for the extension method.
+
+To help avoid conflicts, it's a good practice to prefix extension
+methods with a unique identifier such as domain name.
+
+</ResponseField>
+<ResponseField name="params" type={"object"} required>
+  The parameters for the extension notification, can be any JSON value.
+</ResponseField>
+
 ## <span class="font-mono">FileSystemCapability</span>
 
 File system capabilities that a client may support.

rust/acp.rs

@@ -54,6 +54,7 @@ mod agent;
 mod client;
 mod content;
 mod error;
+mod ext;
 mod plan;
 mod rpc;
 #[cfg(test)]
@@ -66,6 +67,7 @@ pub use agent::*;
 pub use client::*;
 pub use content::*;
 pub use error::*;
+pub use ext::*;
 pub use plan::*;
 pub use stream_broadcast::{
     StreamMessage, StreamMessageContent, StreamMessageDirection, StreamReceiver,
@@ -232,6 +234,38 @@ impl Agent for ClientSideConnection {
             Some(ClientNotification::CancelNotification(notification)),
         )
     }
+
+    async fn ext_method(
+        &self,
+        method: Arc<str>,
+        params: serde_json::Value,
+    ) -> Result<serde_json::Value, Error> {
+        let response: ExtMethodResponse = self
+            .conn
+            .request(
+                EXT_METHOD_NAME,
+                Some(ClientRequest::ExtMethodRequest(ExtMethodRequest {
+                    method,
+                    params,
+                })),
+            )
+            .await?;
+        Ok(response.0)
+    }
+
+    async fn ext_notification(
+        &self,
+        method: Arc<str>,
+        params: serde_json::Value,
+    ) -> Result<(), Error> {
+        self.conn.notify(
+            EXT_NOTIFICATION_NAME,
+            Some(ClientNotification::ExtNotification(ExtNotification {
+                method,
+                params,
+            })),
+        )
+    }
 }
 
 /// Marker type representing the client side of an ACP connection.
@@ -340,6 +374,12 @@ impl<T: Client> MessageHandler<ClientSide> for T {
                 self.kill_terminal(args).await?;
                 Ok(ClientResponse::KillTerminalResponse)
             }
+            AgentRequest::ExtMethodRequest(args) => {
+                let response = self.ext_method(args.method, args.params).await?;
+                Ok(ClientResponse::ExtMethodResponse(ExtMethodResponse(
+                    response,
+                )))
+            }
         }
     }
 
@@ -348,6 +388,9 @@ impl<T: Client> MessageHandler<ClientSide> for T {
             AgentNotification::SessionNotification(notification) => {
                 self.session_notification(notification).await?;
             }
+            AgentNotification::ExtNotification(args) => {
+                self.ext_notification(args.method, args.params).await?;
+            }
         }
         Ok(())
     }
@@ -509,6 +552,38 @@ impl Client for AgentSideConnection {
             Some(AgentNotification::SessionNotification(notification)),
         )
     }
+
+    async fn ext_method(
+        &self,
+        method: Arc<str>,
+        params: serde_json::Value,
+    ) -> Result<serde_json::Value, Error> {
+        let response: ExtMethodResponse = self
+            .conn
+            .request(
+                EXT_METHOD_NAME,
+                Some(AgentRequest::ExtMethodRequest(ExtMethodRequest {
+                    method,
+                    params,
+                })),
+            )
+            .await?;
+        Ok(response.0)
+    }
+
+    async fn ext_notification(
+        &self,
+        method: Arc<str>,
+        params: serde_json::Value,
+    ) -> Result<(), Error> {
+        self.conn.notify(
+            EXT_NOTIFICATION_NAME,
+            Some(AgentNotification::ExtNotification(ExtNotification {
+                method,
+                params,
+            })),
+        )
+    }
 }
 
 /// Marker type representing the agent side of an ACP connection.
@@ -595,6 +670,12 @@ impl<T: Agent> MessageHandler<AgentSide> for T {
                 let response = self.set_session_mode(args).await?;
                 Ok(AgentResponse::SetSessionModeResponse(response))
             }
+            ClientRequest::ExtMethodRequest(args) => {
+                let response = self.ext_method(args.method, args.params).await?;
+                Ok(AgentResponse::ExtMethodResponse(ExtMethodResponse(
+                    response,
+                )))
+            }
         }
     }
 
@@ -603,6 +684,9 @@ impl<T: Agent> MessageHandler<AgentSide> for T {
             ClientNotification::CancelNotification(notification) => {
                 self.cancel(notification).await?;
             }
+            ClientNotification::ExtNotification(args) => {
+                self.ext_notification(args.method, args.params).await?;
+            }
         }
         Ok(())
     }

rust/agent.rs

@@ -9,6 +9,9 @@ use anyhow::Result;
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
+use crate::ext::{
+    EXT_METHOD_NAME, EXT_NOTIFICATION_NAME, ExtMethodRequest, ExtMethodResponse, ExtNotification,
+};
 use crate::{ClientCapabilities, ContentBlock, Error, ProtocolVersion, SessionId};
 
 /// Defines the interface that all ACP-compliant agents must implement.
@@ -114,6 +117,24 @@ pub trait Agent {
     ///
     /// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation)
     fn cancel(&self, args: CancelNotification) -> impl Future<Output = Result<(), Error>>;
+
+    /// Extension method
+    ///
+    /// Allows the Client to send an arbitrary request that is not part of the ACP spec.
+    fn ext_method(
+        &self,
+        method: Arc<str>,
+        params: serde_json::Value,
+    ) -> impl Future<Output = Result<serde_json::Value, Error>>;
+
+    /// Extension notification
+    ///
+    /// Allows the Client to send an arbitrary notification that is not part of the ACP spec.
+    fn ext_notification(
+        &self,
+        method: Arc<str>,
+        params: serde_json::Value,
+    ) -> impl Future<Output = Result<(), Error>>;
 }
 
 // Initialize
@@ -581,6 +602,10 @@ pub struct AgentMethodNames {
     pub session_prompt: &'static str,
     /// Notification for cancelling operations.
     pub session_cancel: &'static str,
+    /// Extension method for custom functionality.
+    pub ext_method: &'static str,
+    /// Extension notification for custom functionality.
+    pub ext_notification: &'static str,
 }
 
 /// Constant containing all agent method names.
@@ -593,6 +618,8 @@ pub const AGENT_METHOD_NAMES: AgentMethodNames = AgentMethodNames {
     session_set_mode: SESSION_SET_MODE_METHOD_NAME,
     session_prompt: SESSION_PROMPT_METHOD_NAME,
     session_cancel: SESSION_CANCEL_METHOD_NAME,
+    ext_method: EXT_METHOD_NAME,
+    ext_notification: EXT_NOTIFICATION_NAME,
 };
 
 /// Method name for the initialize request.
@@ -628,6 +655,7 @@ pub enum ClientRequest {
     #[cfg(feature = "unstable")]
     SetSessionModeRequest(SetSessionModeRequest),
     PromptRequest(PromptRequest),
+    ExtMethodRequest(ExtMethodRequest),
 }
 
 /// All possible responses that an agent can send to a client.
@@ -647,6 +675,7 @@ pub enum AgentResponse {
     #[cfg(feature = "unstable")]
     SetSessionModeResponse(SetSessionModeResponse),
     PromptResponse(PromptResponse),
+    ExtMethodResponse(ExtMethodResponse),
 }
 
 /// All possible notifications that a client can send to an agent.
@@ -660,6 +689,7 @@ pub enum AgentResponse {
 #[schemars(extend("x-docs-ignore" = true))]
 pub enum ClientNotification {
     CancelNotification(CancelNotification),
+    ExtNotification(ExtNotification),
 }
 
 /// Notification to cancel ongoing operations for a session.

rust/client.rs

@@ -11,6 +11,9 @@ use serde::{Deserialize, Serialize};
 
 #[cfg(feature = "unstable")]
 use crate::SessionModeId;
+use crate::ext::{
+    EXT_METHOD_NAME, EXT_NOTIFICATION_NAME, ExtMethodRequest, ExtMethodResponse, ExtNotification,
+};
 use crate::{ContentBlock, Error, Plan, SessionId, ToolCall, ToolCallUpdate};
 
 /// Defines the interface that ACP-compliant clients must implement.
@@ -120,6 +123,24 @@ pub trait Client {
     #[doc(hidden)]
     #[cfg(feature = "unstable")]
     fn kill_terminal(&self, args: KillTerminalRequest) -> impl Future<Output = Result<(), Error>>;
+
+    /// Extension method
+    ///
+    /// Allows the Agent to send an arbitrary request that is not part of the ACP spec.
+    fn ext_method(
+        &self,
+        method: Arc<str>,
+        params: serde_json::Value,
+    ) -> impl Future<Output = Result<serde_json::Value, Error>>;
+
+    /// Extension notification
+    ///
+    /// Allows the Agent to send an arbitrary notifiation that is not part of the ACP spec.
+    fn ext_notification(
+        &self,
+        method: Arc<str>,
+        params: serde_json::Value,
+    ) -> impl Future<Output = Result<(), Error>>;
 }
 
 // Session updates
@@ -560,6 +581,10 @@ pub struct ClientMethodNames {
     /// Method for killing a terminal.
     #[cfg(feature = "unstable")]
     pub terminal_kill: &'static str,
+    /// Extension method for custom functionality.
+    pub ext_method: &'static str,
+    /// Extension notification for custom functionality.
+    pub ext_notification: &'static str,
 }
 
 /// Constant containing all client method names.
@@ -578,6 +603,8 @@ pub const CLIENT_METHOD_NAMES: ClientMethodNames = ClientMethodNames {
     terminal_wait_for_exit: TERMINAL_WAIT_FOR_EXIT_METHOD_NAME,
     #[cfg(feature = "unstable")]
     terminal_kill: TERMINAL_KILL_METHOD_NAME,
+    ext_method: EXT_METHOD_NAME,
+    ext_notification: EXT_NOTIFICATION_NAME,
 };
 
 /// Notification name for session updates.
@@ -627,6 +654,7 @@ pub enum AgentRequest {
     WaitForTerminalExitRequest(WaitForTerminalExitRequest),
     #[cfg(feature = "unstable")]
     KillTerminalRequest(KillTerminalRequest),
+    ExtMethodRequest(ExtMethodRequest),
 }
 
 /// All possible responses that a client can send to an agent.
@@ -652,6 +680,7 @@ pub enum ClientResponse {
     WaitForTerminalExitResponse(WaitForTerminalExitResponse),
     #[cfg(feature = "unstable")]
     KillTerminalResponse,
+    ExtMethodResponse(ExtMethodResponse),
 }
 
 /// All possible notifications that an agent can send to a client.
@@ -663,6 +692,8 @@ pub enum ClientResponse {
 #[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
 #[serde(untagged)]
 #[schemars(extend("x-docs-ignore" = true))]
+#[allow(clippy::large_enum_variant)]
 pub enum AgentNotification {
     SessionNotification(SessionNotification),
+    ExtNotification(ExtNotification),
 }

rust/example_agent.rs

@@ -107,6 +107,32 @@ impl acp::Agent for ExampleAgent {
         log::info!("Received cancel request {args:?}");
         Ok(())
     }
+
+    async fn ext_method(
+        &self,
+        method: std::sync::Arc<str>,
+        params: serde_json::Value,
+    ) -> Result<serde_json::Value, acp::Error> {
+        log::info!(
+            "Received extension method call: method={}, params={:?}",
+            method,
+            params
+        );
+        Ok(serde_json::json!({"example": "response"}))
+    }
+
+    async fn ext_notification(
+        &self,
+        method: std::sync::Arc<str>,
+        params: serde_json::Value,
+    ) -> Result<(), acp::Error> {
+        log::info!(
+            "Received extension notification: method={}, params={:?}",
+            method,
+            params
+        );
+        Ok(())
+    }
 }
 
 #[tokio::main(flavor = "current_thread")]