Copy docs over to request/notif enums

Author: benbrandt

rust/agent.rs

@@ -640,14 +640,90 @@ pub(crate) const SESSION_SET_MODEL_METHOD_NAME: &str = "session/set_model";
 #[serde(untagged)]
 #[schemars(extend("x-docs-ignore" = true))]
 pub enum ClientRequest {
+    /// Establishes the connection with a client and negotiates protocol capabilities.
+    ///
+    /// This method is called once at the beginning of the connection to:
+    /// - Negotiate the protocol version to use
+    /// - Exchange capability information between client and agent
+    /// - Determine available authentication methods
+    ///
+    /// The agent should respond with its supported protocol version and capabilities.
+    ///
+    /// See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/initialization)
     InitializeRequest(InitializeRequest),
+    /// Authenticates the client using the specified authentication method.
+    ///
+    /// Called when the agent requires authentication before allowing session creation.
+    /// The client provides the authentication method ID that was advertised during initialization.
+    ///
+    /// After successful authentication, the client can proceed to create sessions with
+    /// `new_session` without receiving an `auth_required` error.
+    ///
+    /// See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/initialization)
     AuthenticateRequest(AuthenticateRequest),
+    /// Creates a new conversation session with the agent.
+    ///
+    /// Sessions represent independent conversation contexts with their own history and state.
+    ///
+    /// The agent should:
+    /// - Create a new session context
+    /// - Connect to any specified MCP servers
+    /// - Return a unique session ID for future requests
+    ///
+    /// May return an `auth_required` error if the agent requires authentication.
+    ///
+    /// See protocol docs: [Session Setup](https://agentclientprotocol.com/protocol/session-setup)
     NewSessionRequest(NewSessionRequest),
+    /// Loads an existing session to resume a previous conversation.
+    ///
+    /// This method is only available if the agent advertises the `loadSession` capability.
+    ///
+    /// The agent should:
+    /// - Restore the session context and conversation history
+    /// - Connect to the specified MCP servers
+    /// - Stream the entire conversation history back to the client via notifications
+    ///
+    /// See protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/session-setup#loading-sessions)
     LoadSessionRequest(LoadSessionRequest),
+    /// Sets the current mode for a session.
+    ///
+    /// Allows switching between different agent modes (e.g., "ask", "architect", "code")
+    /// that affect system prompts, tool availability, and permission behaviors.
+    ///
+    /// The mode must be one of the modes advertised in `availableModes` during session
+    /// creation or loading. Agents may also change modes autonomously and notify the
+    /// client via `current_mode_update` notifications.
+    ///
+    /// This method can be called at any time during a session, whether the Agent is
+    /// idle or actively generating a response.
+    ///
+    /// See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)
     SetSessionModeRequest(SetSessionModeRequest),
+    /// 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)
     PromptRequest(PromptRequest),
     #[cfg(feature = "unstable")]
+    /// **UNSTABLE**
+    ///
+    /// This capability is not part of the spec yet, and may be removed or changed at any point.
+    ///
+    /// Select a model for a given session.
     SetSessionModelRequest(SetSessionModelRequest),
+    /// 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)
     ExtMethodRequest(ExtRequest),
 }
 
@@ -682,7 +758,24 @@ pub enum AgentResponse {
 #[serde(untagged)]
 #[schemars(extend("x-docs-ignore" = true))]
 pub enum ClientNotification {
+    /// 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)
     CancelNotification(CancelNotification),
+    /// 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)
     ExtNotification(ExtNotification),
 }
 

rust/client.rs

@@ -541,14 +541,90 @@ pub(crate) const TERMINAL_KILL_METHOD_NAME: &str = "terminal/kill";
 #[serde(untagged)]
 #[schemars(extend("x-docs-ignore" = true))]
 pub enum AgentRequest {
+    /// Writes content to a text file in the client's file system.
+    ///
+    /// Only available if the client advertises the `fs.writeTextFile` capability.
+    /// Allows the agent to create or modify files within the client's environment.
+    ///
+    /// See protocol docs: [Client](https://agentclientprotocol.com/protocol/overview#client)
     WriteTextFileRequest(WriteTextFileRequest),
+    /// Reads content from a text file in the client's file system.
+    ///
+    /// Only available if the client advertises the `fs.readTextFile` capability.
+    /// Allows the agent to access file contents within the client's environment.
+    ///
+    /// See protocol docs: [Client](https://agentclientprotocol.com/protocol/overview#client)
     ReadTextFileRequest(ReadTextFileRequest),
+    /// Requests permission from the user for a tool call operation.
+    ///
+    /// Called by the agent when it needs user authorization before executing
+    /// a potentially sensitive operation. The client should present the options
+    /// to the user and return their decision.
+    ///
+    /// If the client cancels the prompt turn via `session/cancel`, it MUST
+    /// respond to this request with `RequestPermissionOutcome::Cancelled`.
+    ///
+    /// See protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/tool-calls#requesting-permission)
     RequestPermissionRequest(RequestPermissionRequest),
+    /// Executes a command in a new terminal
+    ///
+    /// Only available if the `terminal` Client capability is set to `true`.
+    ///
+    /// Returns a `TerminalId` that can be used with other terminal methods
+    /// to get the current output, wait for exit, and kill the command.
+    ///
+    /// The `TerminalId` can also be used to embed the terminal in a tool call
+    /// by using the `ToolCallContent::Terminal` variant.
+    ///
+    /// The Agent is responsible for releasing the terminal by using the `terminal/release`
+    /// method.
+    ///
+    /// See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)
     CreateTerminalRequest(CreateTerminalRequest),
+    /// Gets the terminal output and exit status
+    ///
+    /// Returns the current content in the terminal without waiting for the command to exit.
+    /// If the command has already exited, the exit status is included.
+    ///
+    /// See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)
     TerminalOutputRequest(TerminalOutputRequest),
+    /// Releases a terminal
+    ///
+    /// The command is killed if it hasn't exited yet. Use `terminal/wait_for_exit`
+    /// to wait for the command to exit before releasing the terminal.
+    ///
+    /// After release, the `TerminalId` can no longer be used with other `terminal/*` methods,
+    /// but tool calls that already contain it, continue to display its output.
+    ///
+    /// The `terminal/kill` method can be used to terminate the command without releasing
+    /// the terminal, allowing the Agent to call `terminal/output` and other methods.
+    ///
+    /// See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)
     ReleaseTerminalRequest(ReleaseTerminalRequest),
+    /// Waits for the terminal command to exit and return its exit status
+    ///
+    /// See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)
     WaitForTerminalExitRequest(WaitForTerminalExitRequest),
+    /// Kills the terminal command without releasing the terminal
+    ///
+    /// While `terminal/release` will also kill the command, this method will keep
+    /// the `TerminalId` valid so it can be used with other methods.
+    ///
+    /// This method can be helpful when implementing command timeouts which terminate
+    /// the command as soon as elapsed, and then get the final output so it can be sent
+    /// to the model.
+    ///
+    /// Note: `terminal/release` when `TerminalId` is no longer needed.
+    ///
+    /// See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)
     KillTerminalCommandRequest(KillTerminalCommandRequest),
+    /// Handles extension method requests from the agent.
+    ///
+    /// Allows the Agent to send an arbitrary request that is not part of the ACP spec.
+    /// Extension methods provide a way to add custom functionality while maintaining
+    /// protocol compatibility.
+    ///
+    /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
     ExtMethodRequest(ExtRequest),
 }
 
@@ -584,6 +660,24 @@ pub enum ClientResponse {
 #[allow(clippy::large_enum_variant)]
 #[schemars(extend("x-docs-ignore" = true))]
 pub enum AgentNotification {
+    /// 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)
     SessionNotification(SessionNotification),
+    /// Handles extension notifications from the agent.
+    ///
+    /// Allows the Agent to send an arbitrary notification that is not part of the ACP spec.
+    /// 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)
     ExtNotification(ExtNotification),
 }