Correctly treat capability-based methods as optional in SDKs (agentclientprotocol#123)

Author: benbrandt

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.4.4 (2025-09-30)
+
+### Protocol
+
+- No changes
+
+### Rust
+
+- Provide default trait implementations for optional capability-based `Agent` and `Client` methods.
+
+### Typescript
+
+- Correctly mark capability-based `Agent` and `Client` methods as optional.
+
 ## 0.4.3 (2025-09-25)
 
 ### Protocol

Cargo.lock

@@ -1,7 +1,7 @@
 [package]
 name = "agent-client-protocol"
 authors = ["Zed <hi@zed.dev>"]
-version = "0.4.3"
+version = "0.4.4"
 edition = "2024"
 license = "Apache-2.0"
 description = "A protocol for standardizing communication between code editors and AI coding agents"

Cargo.toml

@@ -1,6 +1,6 @@
 {
   "name": "@zed-industries/agent-client-protocol",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "publishConfig": {
     "access": "public"
   },

package-lock.json

@@ -60,6 +60,32 @@ pub trait Agent {
     /// See protocol docs: [Session Setup](https://agentclientprotocol.com/protocol/session-setup)
     async fn new_session(&self, args: NewSessionRequest) -> Result<NewSessionResponse, Error>;
 
+    /// Processes a user prompt within a session.
+    ///
+    /// This method handles the whole lifecycle of a prompt:
+    /// - Receives user messages with optional context (files, images, etc.)
+    /// - Processes the prompt using language models
+    /// - Reports language model content and tool calls to the Clients
+    /// - Requests permission to run tools
+    /// - Executes any requested tool calls
+    /// - Returns when the turn is complete with a stop reason
+    ///
+    /// See protocol docs: [Prompt Turn](https://agentclientprotocol.com/protocol/prompt-turn)
+    async fn prompt(&self, args: PromptRequest) -> Result<PromptResponse, Error>;
+
+    /// Cancels ongoing operations for a session.
+    ///
+    /// This is a notification sent by the client to cancel an ongoing prompt turn.
+    ///
+    /// Upon receiving this notification, the Agent SHOULD:
+    /// - Stop all language model requests as soon as possible
+    /// - Abort all tool call invocations in progress
+    /// - Send any pending `session/update` notifications
+    /// - Respond to the original `session/prompt` request with `StopReason::Cancelled`
+    ///
+    /// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation)
+    async fn cancel(&self, args: CancelNotification) -> Result<(), Error>;
+
     /// Loads an existing session to resume a previous conversation.
     ///
     /// This method is only available if the agent advertises the `loadSession` capability.
@@ -70,7 +96,9 @@ pub trait Agent {
     /// - Stream the entire conversation history back to the client via notifications
     ///
     /// See protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/session-setup#loading-sessions)
-    async fn load_session(&self, args: LoadSessionRequest) -> Result<LoadSessionResponse, Error>;
+    async fn load_session(&self, _args: LoadSessionRequest) -> Result<LoadSessionResponse, Error> {
+        Err(Error::method_not_found())
+    }
 
     /// Sets the current mode for a session.
     ///
@@ -87,34 +115,10 @@ pub trait Agent {
     /// See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)
     async fn set_session_mode(
         &self,
-        args: SetSessionModeRequest,
-    ) -> Result<SetSessionModeResponse, Error>;
-
-    /// Processes a user prompt within a session.
-    ///
-    /// This method handles the whole lifecycle of a prompt:
-    /// - Receives user messages with optional context (files, images, etc.)
-    /// - Processes the prompt using language models
-    /// - Reports language model content and tool calls to the Clients
-    /// - Requests permission to run tools
-    /// - Executes any requested tool calls
-    /// - Returns when the turn is complete with a stop reason
-    ///
-    /// See protocol docs: [Prompt Turn](https://agentclientprotocol.com/protocol/prompt-turn)
-    async fn prompt(&self, args: PromptRequest) -> Result<PromptResponse, Error>;
-
-    /// Cancels ongoing operations for a session.
-    ///
-    /// This is a notification sent by the client to cancel an ongoing prompt turn.
-    ///
-    /// Upon receiving this notification, the Agent SHOULD:
-    /// - Stop all language model requests as soon as possible
-    /// - Abort all tool call invocations in progress
-    /// - Send any pending `session/update` notifications
-    /// - Respond to the original `session/prompt` request with `StopReason::Cancelled`
-    ///
-    /// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation)
-    async fn cancel(&self, args: CancelNotification) -> Result<(), Error>;
+        _args: SetSessionModeRequest,
+    ) -> Result<SetSessionModeResponse, Error> {
+        Err(Error::method_not_found())
+    }
 
     /// **UNSTABLE**
     ///
@@ -124,24 +128,30 @@ pub trait Agent {
     #[cfg(feature = "unstable")]
     async fn set_session_model(
         &self,
-        args: SetSessionModelRequest,
-    ) -> Result<SetSessionModelResponse, Error>;
+        _args: SetSessionModelRequest,
+    ) -> Result<SetSessionModelResponse, Error> {
+        Err(Error::method_not_found())
+    }
 
     /// Handles extension method requests from the client.
     ///
     /// Extension methods provide a way to add custom functionality while maintaining
     /// protocol compatibility.
     ///
     /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
-    async fn ext_method(&self, args: ExtRequest) -> Result<ExtResponse, Error>;
+    async fn ext_method(&self, _args: ExtRequest) -> Result<ExtResponse, Error> {
+        Ok(RawValue::NULL.to_owned().into())
+    }
 
     /// Handles extension notifications from the client.
     ///
     /// Extension notifications provide a way to send one-way messages for custom functionality
     /// while maintaining protocol compatibility.
     ///
     /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
-    async fn ext_notification(&self, args: ExtNotification) -> Result<(), Error>;
+    async fn ext_notification(&self, _args: ExtNotification) -> Result<(), Error> {
+        Ok(())
+    }
 }
 
 #[async_trait::async_trait(?Send)]

package.json

@@ -37,6 +37,19 @@ pub trait Client {
         args: RequestPermissionRequest,
     ) -> Result<RequestPermissionResponse, Error>;
 
+    /// Handles session update notifications from the agent.
+    ///
+    /// This is a notification endpoint (no response expected) that receives
+    /// real-time updates about session progress, including message chunks,
+    /// tool calls, and execution plans.
+    ///
+    /// Note: Clients SHOULD continue accepting tool call updates even after
+    /// sending a `session/cancel` notification, as the agent may send final
+    /// updates before responding with the cancelled stop reason.
+    ///
+    /// See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output)
+    async fn session_notification(&self, args: SessionNotification) -> Result<(), Error>;
+
     /// Writes content to a text file in the client's file system.
     ///
     /// Only available if the client advertises the `fs.writeTextFile` capability.
@@ -45,8 +58,10 @@ pub trait Client {
     /// See protocol docs: [Client](https://agentclientprotocol.com/protocol/overview#client)
     async fn write_text_file(
         &self,
-        args: WriteTextFileRequest,
-    ) -> Result<WriteTextFileResponse, Error>;
+        _args: WriteTextFileRequest,
+    ) -> Result<WriteTextFileResponse, Error> {
+        Err(Error::method_not_found())
+    }
 
     /// Reads content from a text file in the client's file system.
     ///
@@ -56,21 +71,10 @@ pub trait Client {
     /// See protocol docs: [Client](https://agentclientprotocol.com/protocol/overview#client)
     async fn read_text_file(
         &self,
-        args: ReadTextFileRequest,
-    ) -> Result<ReadTextFileResponse, Error>;
-
-    /// Handles session update notifications from the agent.
-    ///
-    /// This is a notification endpoint (no response expected) that receives
-    /// real-time updates about session progress, including message chunks,
-    /// tool calls, and execution plans.
-    ///
-    /// Note: Clients SHOULD continue accepting tool call updates even after
-    /// sending a `session/cancel` notification, as the agent may send final
-    /// updates before responding with the cancelled stop reason.
-    ///
-    /// See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output)
-    async fn session_notification(&self, args: SessionNotification) -> Result<(), Error>;
+        _args: ReadTextFileRequest,
+    ) -> Result<ReadTextFileResponse, Error> {
+        Err(Error::method_not_found())
+    }
 
     /// Executes a command in a new terminal
     ///
@@ -88,8 +92,10 @@ pub trait Client {
     /// See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)
     async fn create_terminal(
         &self,
-        args: CreateTerminalRequest,
-    ) -> Result<CreateTerminalResponse, Error>;
+        _args: CreateTerminalRequest,
+    ) -> Result<CreateTerminalResponse, Error> {
+        Err(Error::method_not_found())
+    }
 
     /// Gets the terminal output and exit status
     ///
@@ -99,8 +105,10 @@ pub trait Client {
     /// See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)
     async fn terminal_output(
         &self,
-        args: TerminalOutputRequest,
-    ) -> Result<TerminalOutputResponse, Error>;
+        _args: TerminalOutputRequest,
+    ) -> Result<TerminalOutputResponse, Error> {
+        Err(Error::method_not_found())
+    }
 
     /// Releases a terminal
     ///
@@ -116,16 +124,20 @@ pub trait Client {
     /// See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)
     async fn release_terminal(
         &self,
-        args: ReleaseTerminalRequest,
-    ) -> Result<ReleaseTerminalResponse, Error>;
+        _args: ReleaseTerminalRequest,
+    ) -> Result<ReleaseTerminalResponse, Error> {
+        Err(Error::method_not_found())
+    }
 
     /// Waits for the terminal command to exit and return its exit status
     ///
     /// See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)
     async fn wait_for_terminal_exit(
         &self,
-        args: WaitForTerminalExitRequest,
-    ) -> Result<WaitForTerminalExitResponse, Error>;
+        _args: WaitForTerminalExitRequest,
+    ) -> Result<WaitForTerminalExitResponse, Error> {
+        Err(Error::method_not_found())
+    }
 
     /// Kills the terminal command without releasing the terminal
     ///
@@ -141,8 +153,10 @@ pub trait Client {
     /// See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)
     async fn kill_terminal_command(
         &self,
-        args: KillTerminalCommandRequest,
-    ) -> Result<KillTerminalCommandResponse, Error>;
+        _args: KillTerminalCommandRequest,
+    ) -> Result<KillTerminalCommandResponse, Error> {
+        Err(Error::method_not_found())
+    }
 
     /// Handles extension method requests from the agent.
     ///
@@ -151,7 +165,9 @@ pub trait Client {
     /// protocol compatibility.
     ///
     /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
-    async fn ext_method(&self, args: ExtRequest) -> Result<ExtResponse, Error>;
+    async fn ext_method(&self, _args: ExtRequest) -> Result<ExtResponse, Error> {
+        Ok(RawValue::NULL.to_owned().into())
+    }
 
     /// Handles extension notifications from the agent.
     ///
@@ -160,7 +176,9 @@ pub trait Client {
     /// while maintaining protocol compatibility.
     ///
     /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
-    async fn ext_notification(&self, args: ExtNotification) -> Result<(), Error>;
+    async fn ext_notification(&self, _args: ExtNotification) -> Result<(), Error> {
+        Ok(())
+    }
 }
 
 #[async_trait::async_trait(?Send)]

rust/agent.rs

@@ -399,14 +399,14 @@ export class ClientSideConnection implements Agent {
         case schema.CLIENT_METHODS.fs_write_text_file: {
           const validatedParams =
             schema.writeTextFileRequestSchema.parse(params);
-          return client.writeTextFile(
+          return client.writeTextFile?.(
             validatedParams as schema.WriteTextFileRequest,
           );
         }
         case schema.CLIENT_METHODS.fs_read_text_file: {
           const validatedParams =
             schema.readTextFileRequestSchema.parse(params);
-          return client.readTextFile(
+          return client.readTextFile?.(
             validatedParams as schema.ReadTextFileRequest,
           );
         }
@@ -1034,7 +1034,7 @@ export interface Client {
    *
    * See protocol docs: [Client](https://agentclientprotocol.com/protocol/overview#client)
    */
-  writeTextFile(
+  writeTextFile?(
     params: schema.WriteTextFileRequest,
   ): Promise<schema.WriteTextFileResponse>;
   /**
@@ -1045,7 +1045,7 @@ export interface Client {
    *
    * See protocol docs: [Client](https://agentclientprotocol.com/protocol/overview#client)
    */
-  readTextFile(
+  readTextFile?(
     params: schema.ReadTextFileRequest,
   ): Promise<schema.ReadTextFileResponse>;