diff --git a/AGENTS.md b/AGENTS.md index 341acb32..38ecb09f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,9 +19,7 @@ All paths in the protocol should be absolute - Add constants for the method names - Add variants to {Agent|Client}{Request|Response} enums -- Add the methods to the Client/Agent impl of {Agent|Client}SideConnection in src/acp.rs - Handle the new method in the `Side::decode_request`/`Side::decode_notification` implementation -- Handle the new request in the blanket impl of MessageHandler<{Agent|Client}Side> - Add the method to markdown_generator.rs SideDocs functions - Run `npm run generate` and fix any issues that appear - Run `npm run check` diff --git a/Cargo.toml b/Cargo.toml index 1b429a39..f9d08063 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -19,6 +19,7 @@ unstable = [ "unstable_cancel_request", "unstable_elicitation", "unstable_logout", + "unstable_nes", "unstable_session_additional_directories", "unstable_session_fork", "unstable_session_model", @@ -32,6 +33,7 @@ unstable_auth_methods = [] unstable_cancel_request = [] unstable_elicitation = [] unstable_logout = [] +unstable_nes = [] unstable_session_additional_directories = [] unstable_session_fork = [] unstable_session_model = [] diff --git a/docs/protocol/draft/schema.mdx b/docs/protocol/draft/schema.mdx index 92466bcf..ebc6338c 100644 --- a/docs/protocol/draft/schema.mdx +++ b/docs/protocol/draft/schema.mdx @@ -62,6 +62,180 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte + +### document/didChange + +**UNSTABLE** + +Notification sent when a file is edited. + +#### DidChangeDocumentNotification + +Notification sent when a file is edited. + +**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/extensibility) + + +TextDocumentContentChangeEvent[]} required> + The content changes. + +SessionId} required> + The session ID for this notification. + + + The URI of the changed document. + + + The new version number of the document. + + + +### document/didClose + +**UNSTABLE** + +Notification sent when a file is closed. + +#### DidCloseDocumentNotification + +Notification sent when a file is closed. + +**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/extensibility) + + +SessionId} required> + The session ID for this notification. + + + The URI of the closed document. + + + +### document/didFocus + +**UNSTABLE** + +Notification sent when a file becomes the active editor tab. + +#### DidFocusDocumentNotification + +Notification sent when a file becomes the active editor tab. + +**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/extensibility) + + +Position} required> + The current cursor position. + +SessionId} required> + The session ID for this notification. + + + The URI of the focused document. + + + The version number of the document. + +Range} required> + The portion of the file currently visible in the editor viewport. + + + +### document/didOpen + +**UNSTABLE** + +Notification sent when a file is opened in the editor. + +#### DidOpenDocumentNotification + +Notification sent when a file is opened in the editor. + +**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/extensibility) + + + + The language identifier of the document (e.g., "rust", "python"). + +SessionId} required> + The session ID for this notification. + + + The full text content of the document. + + + The URI of the opened document. + + + The version number of the document. + + + +### document/didSave + +**UNSTABLE** + +Notification sent when a file is saved. + +#### DidSaveDocumentNotification + +Notification sent when a file is saved. + +**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/extensibility) + + +SessionId} required> + The session ID for this notification. + + + The URI of the saved document. + + ### initialize Establishes the connection with a client and negotiates protocol capabilities. @@ -213,27 +387,16 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte - -### session/cancel - -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` + +### nes/accept -See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation) +**UNSTABLE** -#### CancelNotification +Notification sent when a suggestion is accepted. -Notification to cancel ongoing operations for a session. +#### AcceptNesNotification -See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation) +Notification sent when a suggestion is accepted. **Type:** Object @@ -246,38 +409,32 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + + + The ID of the accepted suggestion. SessionId} required> - The ID of the session to cancel operations for. + The session ID for this notification. - -### session/close + +### nes/close **UNSTABLE** This capability is not part of the spec yet, and may be removed or changed at any point. -Closes an active session and frees up any resources associated with it. - -This method is only available if the agent advertises the `session.close` capability. - -The agent must cancel any ongoing work (as if `session/cancel` was called) -and then free up any resources associated with the session. - -#### CloseSessionRequest - -**UNSTABLE** +Closes an active NES session and frees up any resources associated with it. -This capability is not part of the spec yet, and may be removed or changed at any point. +The agent must cancel any ongoing work and then free up any resources +associated with the NES session. -Request parameters for closing an active session. +#### CloseNesRequest -If supported, the agent **must** cancel any ongoing work related to the session -(treat it as if `session/cancel` was called) and then free up any resources -associated with the session. +Request to close an NES session. -Only available if the Agent supports the `session.close` capability. +The agent **must** cancel any ongoing work related to the NES session +and then free up any resources associated with the session. **Type:** Object @@ -292,16 +449,12 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte SessionId} required> - The ID of the session to close. + The ID of the NES session to close. -#### CloseSessionResponse - -**UNSTABLE** - -This capability is not part of the spec yet, and may be removed or changed at any point. +#### CloseNesResponse -Response from closing a session. +Response from closing an NES session. **Type:** Object @@ -316,33 +469,16 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte - -### session/fork - -**UNSTABLE** - -This capability is not part of the spec yet, and may be removed or changed at any point. - -Forks an existing session to create a new independent session. - -This method is only available if the agent advertises the `session.fork` capability. - -The agent should create a new session with the same conversation context as the -original, allowing operations like generating summaries without affecting the -original session's history. - -#### ForkSessionRequest + +### nes/reject **UNSTABLE** -This capability is not part of the spec yet, and may be removed or changed at any point. - -Request parameters for forking an existing session. +Notification sent when a suggestion is rejected. -Creates a new session based on the context of an existing one, allowing -operations like generating summaries without affecting the original session's history. +#### RejectNesNotification -Only available if the Agent supports the `session.fork` capability. +Notification sent when a suggestion is rejected. **Type:** Object @@ -356,35 +492,28 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -"string"[]} > - **UNSTABLE** - -This capability is not part of the spec yet, and may be removed or changed at any point. - -Additional workspace roots to activate for this session. Each path must be absolute. - -When omitted or empty, no additional roots are activated. When non-empty, -this is the complete resulting additional-root list for the forked -session. - - - - The working directory for this session. + + The ID of the rejected suggestion. -McpServer[]} > - List of MCP servers to connect to for this session. +NesRejectReason | null} > + The reason for rejection. SessionId} required> - The ID of the session to fork. + The session ID for this notification. -#### ForkSessionResponse + +### nes/start **UNSTABLE** This capability is not part of the spec yet, and may be removed or changed at any point. -Response from forking an existing session. +Starts an NES session. + +#### StartNesRequest + +Request to start an NES session. **Type:** Object @@ -398,41 +527,48 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -SessionConfigOption[] | null} > - Initial session configuration options if supported by the Agent. +NesRepository | null} > + Repository metadata, if the workspace is a git repository. + +WorkspaceFolder[] | null} > + The workspace folders. + + + The root URI of the workspace. -SessionModelState | null} > - **UNSTABLE** -This capability is not part of the spec yet, and may be removed or changed at any point. +#### StartNesResponse -Initial model state if supported by the Agent +Response to `nes/start`. - -SessionModeState | null} > - Initial mode state if supported by the Agent +**Type:** Object -See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes) +**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/extensibility) SessionId} required> - Unique identifier for the newly created forked session. + The session ID for the newly started NES session. - -### session/list - -Lists existing sessions known to the agent. + +### nes/suggest -This method is only available if the agent advertises the `sessionCapabilities.list` capability. +**UNSTABLE** -The agent should return metadata about sessions with optional filtering and pagination support. +This capability is not part of the spec yet, and may be removed or changed at any point. -#### ListSessionsRequest +Requests a code suggestion. -Request parameters for listing existing sessions. +#### SuggestNesRequest -Only available if the Agent supports the `sessionCapabilities.list` capability. +Request for a code suggestion. **Type:** Object @@ -446,27 +582,31 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -"string"[]} > - **UNSTABLE** - -This capability is not part of the spec yet, and may be removed or changed at any point. - -Filter sessions by the exact ordered additional workspace roots. Each path must be absolute. - -This filter applies only when the field is present and non-empty. When -omitted or empty, no additional-root filter is applied. - +NesSuggestContext | null} > + Context for the suggestion, included based on agent capabilities. - - Opaque cursor token from a previous response's nextCursor field for cursor-based pagination +Position} required> + The current cursor position. - - Filter sessions by working directory. Must be an absolute path. +Range | null} > + The current text selection range, if any. + +SessionId} required> + The session ID for this request. + +NesTriggerKind} required> + What triggered this suggestion request. + + + The URI of the document to suggest for. + + + The version number of the document. -#### ListSessionsResponse +#### SuggestNesResponse -Response from listing sessions. +Response to `nes/suggest`. **Type:** Object @@ -480,36 +620,31 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - - Opaque cursor token. If present, pass this in the next request's cursor parameter -to fetch the next page. If absent, there are no more results. - -SessionInfo[]} required> - Array of session information objects +NesSuggestion[]} required> + The list of suggestions. - -### session/load - -Loads an existing session to resume a previous conversation. + +### session/cancel -This method is only available if the agent advertises the `loadSession` capability. +Cancels ongoing operations for a session. -The agent should: +This is a notification sent by the client to cancel an ongoing prompt turn. -- Restore the session context and conversation history -- Connect to the specified MCP servers -- Stream the entire conversation history back to the client via notifications +Upon receiving this notification, the Agent SHOULD: -See protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/session-setup#loading-sessions) +- 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` -#### LoadSessionRequest +See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation) -Request parameters for loading an existing session. +#### CancelNotification -Only available if the Agent supports the `loadSession` capability. +Notification to cancel ongoing operations for a session. -See protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/session-setup#loading-sessions) +See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation) **Type:** Object @@ -523,31 +658,37 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -"string"[]} > - **UNSTABLE** +SessionId} required> + The ID of the session to cancel operations for. + + + +### session/close + +**UNSTABLE** This capability is not part of the spec yet, and may be removed or changed at any point. -Additional workspace roots to activate for this session. Each path must be absolute. +Closes an active session and frees up any resources associated with it. -When omitted or empty, no additional roots are activated. When non-empty, -this is the complete resulting additional-root list for the loaded -session. +This method is only available if the agent advertises the `session.close` capability. - - - The working directory for this session. - -McpServer[]} required> - List of MCP servers to connect to for this session. - -SessionId} required> - The ID of the session to load. - +The agent must cancel any ongoing work (as if `session/cancel` was called) +and then free up any resources associated with the session. -#### LoadSessionResponse +#### CloseSessionRequest -Response from loading an existing session. +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Request parameters for closing an active session. + +If supported, the agent **must** cancel any ongoing work related to the session +(treat it as if `session/cancel` was called) and then free up any resources +associated with the session. + +Only available if the Agent supports the `session.close` capability. **Type:** Object @@ -561,46 +702,58 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -SessionConfigOption[] | null} > - Initial session configuration options if supported by the Agent. +SessionId} required> + The ID of the session to close. -SessionModelState | null} > - **UNSTABLE** + +#### CloseSessionResponse + +**UNSTABLE** This capability is not part of the spec yet, and may be removed or changed at any point. -Initial model state if supported by the Agent +Response from closing a session. - -SessionModeState | null} > - Initial mode state if supported by the Agent +**Type:** Object -See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes) +**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/extensibility) - -### session/new + +### session/fork -Creates a new conversation session with the agent. +**UNSTABLE** -Sessions represent independent conversation contexts with their own history and state. +This capability is not part of the spec yet, and may be removed or changed at any point. -The agent should: +Forks an existing session to create a new independent session. -- Create a new session context -- Connect to any specified MCP servers -- Return a unique session ID for future requests +This method is only available if the agent advertises the `session.fork` capability. -May return an `auth_required` error if the agent requires authentication. +The agent should create a new session with the same conversation context as the +original, allowing operations like generating summaries without affecting the +original session's history. -See protocol docs: [Session Setup](https://agentclientprotocol.com/protocol/session-setup) +#### ForkSessionRequest -#### NewSessionRequest +**UNSTABLE** -Request parameters for creating a new session. +This capability is not part of the spec yet, and may be removed or changed at any point. -See protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/session-setup#creating-a-session) +Request parameters for forking an existing session. + +Creates a new session based on the context of an existing one, allowing +operations like generating summaries without affecting the original session's history. + +Only available if the Agent supports the `session.fork` capability. **Type:** Object @@ -619,25 +772,30 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte This capability is not part of the spec yet, and may be removed or changed at any point. -Additional workspace roots for this session. Each path must be absolute. +Additional workspace roots to activate for this session. Each path must be absolute. -These expand the session's filesystem scope without changing `cwd`, which -remains the base for relative paths. When omitted or empty, no -additional roots are activated for the new session. +When omitted or empty, no additional roots are activated. When non-empty, +this is the complete resulting additional-root list for the forked +session. - The working directory for this session. Must be an absolute path. + The working directory for this session. -McpServer[]} required> - List of MCP (Model Context Protocol) servers the agent should connect to. +McpServer[]} > + List of MCP servers to connect to for this session. + +SessionId} required> + The ID of the session to fork. -#### NewSessionResponse +#### ForkSessionResponse -Response from creating a new session. +**UNSTABLE** -See protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/session-setup#creating-a-session) +This capability is not part of the spec yet, and may be removed or changed at any point. + +Response from forking an existing session. **Type:** Object @@ -669,35 +827,23 @@ See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/sess SessionId} required> - Unique identifier for the created session. - -Used in all subsequent requests for this conversation. - + Unique identifier for the newly created forked session. - -### session/prompt - -Processes a user prompt within a session. - -This method handles the whole lifecycle of a prompt: + +### session/list -- 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 +Lists existing sessions known to the agent. -See protocol docs: [Prompt Turn](https://agentclientprotocol.com/protocol/prompt-turn) +This method is only available if the agent advertises the `sessionCapabilities.list` capability. -#### PromptRequest +The agent should return metadata about sessions with optional filtering and pagination support. -Request parameters for sending a user prompt to the agent. +#### ListSessionsRequest -Contains the user's message and any additional context. +Request parameters for listing existing sessions. -See protocol docs: [User Message](https://agentclientprotocol.com/protocol/prompt-turn#1-user-message) +Only available if the Agent supports the `sessionCapabilities.list` capability. **Type:** Object @@ -711,43 +857,27 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - +"string"[]} > **UNSTABLE** This capability is not part of the spec yet, and may be removed or changed at any point. -A client-generated unique identifier for this user message. +Filter sessions by the exact ordered additional workspace roots. Each path must be absolute. -If provided, the Agent SHOULD echo this value as `userMessageId` in the -`PromptResponse` to confirm it was recorded. -Both clients and agents MUST use UUID format for message IDs. +This filter applies only when the field is present and non-empty. When +omitted or empty, no additional-root filter is applied. -ContentBlock[]} required> - The blocks of content that compose the user's message. - -As a baseline, the Agent MUST support `ContentBlock::Text` and `ContentBlock::ResourceLink`, -while other variants are optionally enabled via `PromptCapabilities`. - -The Client MUST adapt its interface according to `PromptCapabilities`. - -The client MAY include referenced pieces of context as either -`ContentBlock::Resource` or `ContentBlock::ResourceLink`. - -When available, `ContentBlock::Resource` is preferred -as it avoids extra round-trips and allows the message to include -pieces of context from sources the agent may not have access to. - + + Opaque cursor token from a previous response's nextCursor field for cursor-based pagination -SessionId} required> - The ID of the session to send this user message to + + Filter sessions by working directory. Must be an absolute path. -#### PromptResponse - -Response from processing a user prompt. +#### ListSessionsResponse -See protocol docs: [Check for Completion](https://agentclientprotocol.com/protocol/prompt-turn#4-check-for-completion) +Response from listing sessions. **Type:** Object @@ -761,56 +891,36 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -StopReason} required> - Indicates why the agent stopped processing the turn. + + Opaque cursor token. If present, pass this in the next request's cursor parameter +to fetch the next page. If absent, there are no more results. + +SessionInfo[]} required> + Array of session information objects -Usage | null} > - **UNSTABLE** -This capability is not part of the spec yet, and may be removed or changed at any point. + +### session/load -Token usage for this turn (optional). +Loads an existing session to resume a previous conversation. - - - **UNSTABLE** +This method is only available if the agent advertises the `loadSession` capability. -This capability is not part of the spec yet, and may be removed or changed at any point. - -The acknowledged user message ID. - -If the client provided a `messageId` in the `PromptRequest`, the agent echoes it here -to confirm it was recorded. If the client did not provide one, the agent MAY assign one -and return it here. Absence of this field indicates the agent did not record a message ID. - - - - -### session/resume - -**UNSTABLE** - -This capability is not part of the spec yet, and may be removed or changed at any point. - -Resumes an existing session without returning previous messages. - -This method is only available if the agent advertises the `session.resume` capability. - -The agent should resume the session context, allowing the conversation to continue -without replaying the message history (unlike `session/load`). +The agent should: -#### ResumeSessionRequest +- Restore the session context and conversation history +- Connect to the specified MCP servers +- Stream the entire conversation history back to the client via notifications -**UNSTABLE** +See protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/session-setup#loading-sessions) -This capability is not part of the spec yet, and may be removed or changed at any point. +#### LoadSessionRequest -Request parameters for resuming an existing session. +Request parameters for loading an existing session. -Resumes an existing session without returning previous messages (unlike `session/load`). -This is useful for agents that can resume sessions but don't implement full session loading. +Only available if the Agent supports the `loadSession` capability. -Only available if the Agent supports the `session.resume` capability. +See protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/session-setup#loading-sessions) **Type:** Object @@ -832,27 +942,23 @@ This capability is not part of the spec yet, and may be removed or changed at an Additional workspace roots to activate for this session. Each path must be absolute. When omitted or empty, no additional roots are activated. When non-empty, -this is the complete resulting additional-root list for the resumed +this is the complete resulting additional-root list for the loaded session. The working directory for this session. -McpServer[]} > +McpServer[]} required> List of MCP servers to connect to for this session. SessionId} required> - The ID of the session to resume. + The ID of the session to load. -#### ResumeSessionResponse - -**UNSTABLE** - -This capability is not part of the spec yet, and may be removed or changed at any point. +#### LoadSessionResponse -Response from resuming an existing session. +Response from loading an existing session. **Type:** Object @@ -884,55 +990,28 @@ See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/sess - -### session/set_config_option - -Sets the current value for a session configuration option. - -#### SetSessionConfigOptionRequest - -Request parameters for setting a session configuration option. - -**Type:** Union - - -A boolean value (`type: "boolean"`). - - + +### session/new - - The discriminator value. Must be `"boolean"`. - - - The boolean value. - +Creates a new conversation session with the agent. - - +Sessions represent independent conversation contexts with their own history and state. - -A `SessionConfigValueId` string value. +The agent should: -This is the default when `type` is absent on the wire. Unknown `type` -values with string payloads also gracefully deserialize into this -variant. +- 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. -SessionConfigValueId} - required -> - The value ID. - +See protocol docs: [Session Setup](https://agentclientprotocol.com/protocol/session-setup) - - +#### NewSessionRequest -#### SetSessionConfigOptionResponse +Request parameters for creating a new session. -Response to `session/set_config_option` method. +See protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/session-setup#creating-a-session) **Type:** Object @@ -946,30 +1025,30 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -SessionConfigOption[]} required> - The full set of configuration options and their current values. - - - -### session/set_mode +"string"[]} > + **UNSTABLE** -Sets the current mode for a session. +This capability is not part of the spec yet, and may be removed or changed at any point. -Allows switching between different agent modes (e.g., "ask", "architect", "code") -that affect system prompts, tool availability, and permission behaviors. +Additional workspace roots for this session. Each path must be absolute. -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. +These expand the session's filesystem scope without changing `cwd`, which +remains the base for relative paths. When omitted or empty, no +additional roots are activated for the new session. -This method can be called at any time during a session, whether the Agent is -idle or actively generating a response. + + + The working directory for this session. Must be an absolute path. + +McpServer[]} required> + List of MCP (Model Context Protocol) servers the agent should connect to. + -See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes) +#### NewSessionResponse -#### SetSessionModeRequest +Response from creating a new session. -Request parameters for setting a session mode. +See protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/session-setup#creating-a-session) **Type:** Object @@ -983,46 +1062,53 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -SessionModeId} required> - The ID of the mode to set. - -SessionId} required> - The ID of the session to set the mode for. +SessionConfigOption[] | null} > + Initial session configuration options if supported by the Agent. +SessionModelState | null} > + **UNSTABLE** -#### SetSessionModeResponse +This capability is not part of the spec yet, and may be removed or changed at any point. -Response to `session/set_mode` method. +Initial model state if supported by the Agent -**Type:** Object + +SessionModeState | null} > + Initial mode state if supported by the Agent -**Properties:** +See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes) - - 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. + +SessionId} required> + Unique identifier for the created session. -See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) +Used in all subsequent requests for this conversation. - -### session/set_model + +### session/prompt -**UNSTABLE** +Processes a user prompt within a session. -This capability is not part of the spec yet, and may be removed or changed at any point. +This method handles the whole lifecycle of a prompt: -Select a model for a given session. +- 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 -#### SetSessionModelRequest +See protocol docs: [Prompt Turn](https://agentclientprotocol.com/protocol/prompt-turn) -**UNSTABLE** +#### PromptRequest -This capability is not part of the spec yet, and may be removed or changed at any point. +Request parameters for sending a user prompt to the agent. -Request parameters for setting a session model. +Contains the user's message and any additional context. + +See protocol docs: [User Message](https://agentclientprotocol.com/protocol/prompt-turn#1-user-message) **Type:** Object @@ -1036,57 +1122,43 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -ModelId} required> - The ID of the model to set. - -SessionId} required> - The ID of the session to set the model for. - - -#### SetSessionModelResponse - -**UNSTABLE** + + **UNSTABLE** This capability is not part of the spec yet, and may be removed or changed at any point. -Response to `session/set_model` method. - -**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. +A client-generated unique identifier for this user message. -See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) +If provided, the Agent SHOULD echo this value as `userMessageId` in the +`PromptResponse` to confirm it was recorded. +Both clients and agents MUST use UUID format for message IDs. +ContentBlock[]} required> + The blocks of content that compose the user's message. -## Client - -Defines the interface that ACP-compliant clients must implement. - -Clients are typically code editors (IDEs, text editors) that provide the interface -between users and AI agents. They manage the environment, handle user interactions, -and control access to resources. +As a baseline, the Agent MUST support `ContentBlock::Text` and `ContentBlock::ResourceLink`, +while other variants are optionally enabled via `PromptCapabilities`. - -### fs/read_text_file +The Client MUST adapt its interface according to `PromptCapabilities`. -Reads content from a text file in the client's file system. +The client MAY include referenced pieces of context as either +`ContentBlock::Resource` or `ContentBlock::ResourceLink`. -Only available if the client advertises the `fs.readTextFile` capability. -Allows the agent to access file contents within the client's environment. +When available, `ContentBlock::Resource` is preferred +as it avoids extra round-trips and allows the message to include +pieces of context from sources the agent may not have access to. -See protocol docs: [Client](https://agentclientprotocol.com/protocol/overview#client) + +SessionId} required> + The ID of the session to send this user message to + -#### ReadTextFileRequest +#### PromptResponse -Request to read content from a text file. +Response from processing a user prompt. -Only available if the client supports the `fs.readTextFile` capability. +See protocol docs: [Check for Completion](https://agentclientprotocol.com/protocol/prompt-turn#4-check-for-completion) **Type:** Object @@ -1100,59 +1172,56 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - - Maximum number of lines to read. - - - Minimum: `0` - +StopReason} required> + Indicates why the agent stopped processing the turn. - - Line number to start reading from (1-based). +Usage | null} > + **UNSTABLE** - - Minimum: `0` +This capability is not part of the spec yet, and may be removed or changed at any point. + +Token usage for this turn (optional). - - Absolute path to the file to read. - -SessionId} required> - The session ID for this request. - + + **UNSTABLE** -#### ReadTextFileResponse +This capability is not part of the spec yet, and may be removed or changed at any point. -Response containing the contents of a text file. +The acknowledged user message ID. -**Type:** Object +If the client provided a `messageId` in the `PromptRequest`, the agent echoes it here +to confirm it was recorded. If the client did not provide one, the agent MAY assign one +and return it here. Absence of this field indicates the agent did not record a message ID. -**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. + +### session/resume -See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) +**UNSTABLE** - - - +This capability is not part of the spec yet, and may be removed or changed at any point. - -### fs/write_text_file +Resumes an existing session without returning previous messages. -Writes content to a text file in the client's file system. +This method is only available if the agent advertises the `session.resume` capability. -Only available if the client advertises the `fs.writeTextFile` capability. -Allows the agent to create or modify files within the client's environment. +The agent should resume the session context, allowing the conversation to continue +without replaying the message history (unlike `session/load`). -See protocol docs: [Client](https://agentclientprotocol.com/protocol/overview#client) +#### ResumeSessionRequest -#### WriteTextFileRequest +**UNSTABLE** -Request to write content to a text file. +This capability is not part of the spec yet, and may be removed or changed at any point. -Only available if the client supports the `fs.writeTextFile` capability. +Request parameters for resuming an existing session. + +Resumes an existing session without returning previous messages (unlike `session/load`). +This is useful for agents that can resume sessions but don't implement full session loading. + +Only available if the Agent supports the `session.resume` capability. **Type:** Object @@ -1166,19 +1235,35 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - - The text content to write to the file. +"string"[]} > + **UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Additional workspace roots to activate for this session. Each path must be absolute. + +When omitted or empty, no additional roots are activated. When non-empty, +this is the complete resulting additional-root list for the resumed +session. + - - Absolute path to the file to write. + + The working directory for this session. + +McpServer[]} > + List of MCP servers to connect to for this session. SessionId} required> - The session ID for this request. + The ID of the session to resume. -#### WriteTextFileResponse +#### ResumeSessionResponse -Response to `fs/write_text_file` +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Response from resuming an existing session. **Type:** Object @@ -1192,77 +1277,73 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) +SessionConfigOption[] | null} > + Initial session configuration options if supported by the Agent. + +SessionModelState | null} > + **UNSTABLE** - -### session/elicitation +This capability is not part of the spec yet, and may be removed or changed at any point. -**UNSTABLE** +Initial model state if supported by the Agent -This capability is not part of the spec yet, and may be removed or changed at any point. + +SessionModeState | null} > + Initial mode state if supported by the Agent -Requests structured user input via a form or URL. +See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes) -#### ElicitationRequest + -**UNSTABLE** + +### session/set_config_option -This capability is not part of the spec yet, and may be removed or changed at any point. +Sets the current value for a session configuration option. -Request from the agent to elicit structured user input. +#### SetSessionConfigOptionRequest -The agent sends this to the client to request information from the user, -either via a form or by directing them to a URL. +Request parameters for setting a session configuration option. **Type:** Union - -Form-based elicitation where the client renders a form from the provided schema. + +A boolean value (`type: "boolean"`). - - The discriminator value. Must be `"form"`. + + The discriminator value. Must be `"boolean"`. -ElicitationSchema} - required -> - A JSON Schema describing the form fields to present to the user. + + The boolean value. - -URL-based elicitation where the client directs the user to a URL. + +A `SessionConfigValueId` string value. + +This is the default when `type` is absent on the wire. Unknown `type` +values with string payloads also gracefully deserialize into this +variant. ElicitationId} + name="value" + type={SessionConfigValueId} required > - The unique identifier for this elicitation. - - - The discriminator value. Must be `"url"`. - - - The URL to direct the user to. + The value ID. -#### ElicitationResponse - -**UNSTABLE** - -This capability is not part of the spec yet, and may be removed or changed at any point. +#### SetSessionConfigOptionResponse -Response from the client to an elicitation request. +Response to `session/set_config_option` method. **Type:** Object @@ -1276,26 +1357,30 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -ElicitationAction} required> - The user's action in response to the elicitation. +SessionConfigOption[]} required> + The full set of configuration options and their current values. - -### session/elicitation/complete + +### session/set_mode -**UNSTABLE** +Sets the current mode for a session. -This capability is not part of the spec yet, and may be removed or changed at any point. +Allows switching between different agent modes (e.g., "ask", "architect", "code") +that affect system prompts, tool availability, and permission behaviors. -Notification that a URL-based elicitation has completed. +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. -#### ElicitationCompleteNotification +This method can be called at any time during a session, whether the Agent is +idle or actively generating a response. -**UNSTABLE** +See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes) -This capability is not part of the spec yet, and may be removed or changed at any point. +#### SetSessionModeRequest -Notification sent by the agent when a URL-based elicitation is complete. +Request parameters for setting a session mode. **Type:** Object @@ -1309,31 +1394,46 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -ElicitationId} required> - The ID of the elicitation that completed. +SessionModeId} required> + The ID of the mode to set. + +SessionId} required> + The ID of the session to set the mode for. - -### session/request_permission +#### SetSessionModeResponse -Requests permission from the user for a tool call operation. +Response to `session/set_mode` method. -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. +**Type:** Object -If the client cancels the prompt turn via `session/cancel`, it MUST -respond to this request with `RequestPermissionOutcome::Cancelled`. +**Properties:** -See protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/tool-calls#requesting-permission) + + 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. -#### RequestPermissionRequest +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -Request for user permission to execute a tool call. + -Sent when the agent needs authorization before performing a sensitive operation. + +### session/set_model -See protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/tool-calls#requesting-permission) +**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 + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Request parameters for setting a session model. **Type:** Object @@ -1347,19 +1447,20 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -PermissionOption[]} required> - Available permission options for the user to choose from. +ModelId} required> + The ID of the model to set. SessionId} required> - The session ID for this request. - -ToolCallUpdate} required> - Details about the tool call requiring permission. + The ID of the session to set the model for. -#### RequestPermissionResponse +#### SetSessionModelResponse -Response to a permission request. +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Response to `session/set_model` method. **Type:** Object @@ -1373,73 +1474,30 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -RequestPermissionOutcome} required> - The user's decision on the permission request. - - - -### session/update - -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 - -Notification containing a session update from the agent. - -Used to stream real-time progress and results during prompt processing. - -See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output) - -**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/extensibility) - -SessionId} required> - The ID of the session this update pertains to. - -SessionUpdate} required> - The actual update content. - +## Client - -### terminal/create +Defines the interface that ACP-compliant clients must implement. -Executes a command in a new terminal +Clients are typically code editors (IDEs, text editors) that provide the interface +between users and AI agents. They manage the environment, handle user interactions, +and control access to resources. -Only available if the `terminal` Client capability is set to `true`. + +### fs/read_text_file -Returns a `TerminalId` that can be used with other terminal methods -to get the current output, wait for exit, and kill the command. +Reads content from a text file in the client's file system. -The `TerminalId` can also be used to embed the terminal in a tool call -by using the `ToolCallContent::Terminal` variant. +Only available if the client advertises the `fs.readTextFile` capability. +Allows the agent to access file contents within the client's environment. -The Agent is responsible for releasing the terminal by using the `terminal/release` -method. +See protocol docs: [Client](https://agentclientprotocol.com/protocol/overview#client) -See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals) +#### ReadTextFileRequest -#### CreateTerminalRequest +Request to read content from a text file. -Request to create a new terminal and execute a command. +Only available if the client supports the `fs.readTextFile` capability. **Type:** Object @@ -1453,38 +1511,28 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -"string"[]} > - Array of command arguments. - - - The command to execute. - - - Working directory for the command (absolute path). - -EnvVariable[]} > - Environment variables for the command. - - - Maximum number of output bytes to retain. + + Maximum number of lines to read. -When the limit is exceeded, the Client truncates from the beginning of the output -to stay within the limit. + - Minimum: `0` -The Client MUST ensure truncation happens at a character boundary to maintain valid -string output, even if this means the retained output is slightly less than the -specified limit. + + + Line number to start reading from (1-based). - Minimum: `0` + + Absolute path to the file to read. + SessionId} required> The session ID for this request. -#### CreateTerminalResponse +#### ReadTextFileResponse -Response containing the ID of the created terminal. +Response containing the contents of a text file. **Type:** Object @@ -1498,29 +1546,24 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - - The unique identifier for the created terminal. + - -### terminal/kill - -Kills the terminal command without releasing the terminal + +### fs/write_text_file -While `terminal/release` will also kill the command, this method will keep -the `TerminalId` valid so it can be used with other methods. +Writes content to a text file in the client's file system. -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. +Only available if the client advertises the `fs.writeTextFile` capability. +Allows the agent to create or modify files within the client's environment. -Note: Call `terminal/release` when `TerminalId` is no longer needed. +See protocol docs: [Client](https://agentclientprotocol.com/protocol/overview#client) -See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals) +#### WriteTextFileRequest -#### KillTerminalRequest +Request to write content to a text file. -Request to kill a terminal without releasing it. +Only available if the client supports the `fs.writeTextFile` capability. **Type:** Object @@ -1533,17 +1576,20 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + + + The text content to write to the file. + + + Absolute path to the file to write. SessionId} required> The session ID for this request. - - The ID of the terminal to kill. - -#### KillTerminalResponse +#### WriteTextFileResponse -Response to `terminal/kill` method +Response to `fs/write_text_file` **Type:** Object @@ -1558,42 +1604,76 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte - -### terminal/output + +### session/elicitation -Gets the terminal output and exit status +**UNSTABLE** -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. +This capability is not part of the spec yet, and may be removed or changed at any point. -See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals) +Requests structured user input via a form or URL. -#### TerminalOutputRequest +#### ElicitationRequest -Request to get the current output and status of a terminal. +**UNSTABLE** -**Type:** Object +This capability is not part of the spec yet, and may be removed or changed at any point. -**Properties:** +Request from the agent to elicit structured user input. - - 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. +The agent sends this to the client to request information from the user, +either via a form or by directing them to a URL. -See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) +**Type:** Union + + +Form-based elicitation where the client renders a form from the provided schema. + + + + The discriminator value. Must be `"form"`. -SessionId} required> - The session ID for this request. +ElicitationSchema} + required +> + A JSON Schema describing the form fields to present to the user. - - The ID of the terminal to get output from. + + -#### TerminalOutputResponse + +URL-based elicitation where the client directs the user to a URL. -Response containing the terminal output and exit status. + + +ElicitationId} + required +> + The unique identifier for this elicitation. + + + The discriminator value. Must be `"url"`. + + + The URL to direct the user to. + + + + + +#### ElicitationResponse + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Response from the client to an elicitation request. **Type:** Object @@ -1607,35 +1687,26 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -TerminalExitStatus | null} > - Exit status if the command has completed. - - - The terminal output captured so far. - - - Whether the output was truncated due to byte limits. +ElicitationAction} required> + The user's action in response to the elicitation. - -### terminal/release + +### session/elicitation/complete -Releases a terminal +**UNSTABLE** -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. +This capability is not part of the spec yet, and may be removed or changed at any point. -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. +Notification that a URL-based elicitation has completed. -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. +#### ElicitationCompleteNotification -See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals) +**UNSTABLE** -#### ReleaseTerminalRequest +This capability is not part of the spec yet, and may be removed or changed at any point. -Request to release a terminal and free its resources. +Notification sent by the agent when a URL-based elicitation is complete. **Type:** Object @@ -1649,40 +1720,31 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -SessionId} required> - The session ID for this request. - - - The ID of the terminal to release. +ElicitationId} required> + The ID of the elicitation that completed. -#### ReleaseTerminalResponse + +### session/request_permission -Response to terminal/release method - -**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. +Requests permission from the user for a tool call operation. -See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) +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`. - -### terminal/wait_for_exit +See protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/tool-calls#requesting-permission) -Waits for the terminal command to exit and return its exit status +#### RequestPermissionRequest -See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals) +Request for user permission to execute a tool call. -#### WaitForTerminalExitRequest +Sent when the agent needs authorization before performing a sensitive operation. -Request to wait for a terminal command to exit. +See protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/tool-calls#requesting-permission) **Type:** Object @@ -1695,17 +1757,20 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + +PermissionOption[]} required> + Available permission options for the user to choose from. SessionId} required> The session ID for this request. - - The ID of the terminal to wait for. +ToolCallUpdate} required> + Details about the tool call requiring permission. -#### WaitForTerminalExitResponse +#### RequestPermissionResponse -Response containing the exit status of a terminal command. +Response to a permission request. **Type:** Object @@ -1719,59 +1784,32 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - - The process exit code (may be null if terminated by signal). - - - Minimum: `0` - - - - The signal that terminated the process (may be null if exited normally). +RequestPermissionOutcome} required> + The user's decision on the permission request. -## 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 - -**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: + +### session/update -1. MUST 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: +Handles session update notifications from the agent. -- Valid response with appropriate data (partial results or cancellation marker) -- Error response with code `-32800` (Cancelled) +This is a notification endpoint (no response expected) that receives +real-time updates about session progress, including message chunks, +tool calls, and execution plans. -See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation) +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. -#### CancelRequestNotification +See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output) -**UNSTABLE** +#### SessionNotification -This capability is not part of the spec yet, and may be removed or changed at any point. +Notification containing a session update from the agent. -Notification to cancel an ongoing request. +Used to stream real-time progress and results during prompt processing. -See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation) +See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output) **Type:** Object @@ -1785,17 +1823,34 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -RequestId} required> - The ID of the request to cancel. +SessionId} required> + The ID of the session this update pertains to. + +SessionUpdate} required> + The actual update content. -## AgentAuthCapabilities + +### terminal/create -**UNSTABLE** +Executes a command in a new terminal -This capability is not part of the spec yet, and may be removed or changed at any point. +Only available if the `terminal` Client capability is set to `true`. -Authentication-related capabilities supported by the agent. +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 + +Request to create a new terminal and execute a command. **Type:** Object @@ -1809,21 +1864,38 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -LogoutCapabilities | null} > - Whether the agent supports the logout method. +"string"[]} > + Array of command arguments. + + + The command to execute. + + + Working directory for the command (absolute path). + +EnvVariable[]} > + Environment variables for the command. + + + Maximum number of output bytes to retain. -By supplying `\{\}` it means that the agent supports the logout method. +When the limit is exceeded, the Client truncates from the beginning of the output +to stay within the limit. - +The Client MUST ensure truncation happens at a character boundary to maintain valid +string output, even if this means the retained output is slightly less than the +specified limit. -## AgentCapabilities + - Minimum: `0` -Capabilities supported by the agent. + +SessionId} required> + The session ID for this request. + -Advertised during initialization to inform the client about -available features and content types. +#### CreateTerminalResponse -See protocol docs: [Agent Capabilities](https://agentclientprotocol.com/protocol/initialization#agent-capabilities) +Response containing the ID of the created terminal. **Type:** Object @@ -1837,43 +1909,29 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -AgentAuthCapabilities} > - **UNSTABLE** - -This capability is not part of the spec yet, and may be removed or changed at any point. - -Authentication-related capabilities supported by the agent. - - - Default: `{}` - - - - Whether the agent supports `session/load`. - - - Default: `false` - + + The unique identifier for the created terminal. -McpCapabilities} > - MCP capabilities supported by the agent. - - Default: `{"http":false,"sse":false}` + +### terminal/kill - -PromptCapabilities} > - Prompt capabilities supported by the agent. +Kills the terminal command without releasing the terminal - - Default: `{"audio":false,"embeddedContext":false,"image":false}` +While `terminal/release` will also kill the command, this method will keep +the `TerminalId` valid so it can be used with other methods. - -SessionCapabilities} > +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. - - Default: `{}` +Note: Call `terminal/release` when `TerminalId` is no longer needed. - +See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals) -## Annotations +#### KillTerminalRequest -Optional annotations for the client. The client can use annotations to inform how objects are used or displayed +Request to kill a terminal without releasing it. **Type:** Object @@ -1887,16 +1945,16 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -Role[] | null} > - - +SessionId} required> + The session ID for this request. - + + The ID of the terminal to kill. -## AudioContent +#### KillTerminalResponse -Audio provided to or from an LLM. +Response to `terminal/kill` method **Type:** Object @@ -1909,25 +1967,21 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - -Annotations | null} > - - - - -## AuthCapabilities + +### terminal/output -**UNSTABLE** +Gets the terminal output and exit status -This capability is not part of the spec yet, and may be removed or changed at any point. +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. -Authentication capabilities supported by the client. +See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals) -Advertised during initialization to inform the agent which authentication -method types the client can handle. This governs opt-in types that require -additional client-side support. +#### TerminalOutputRequest + +Request to get the current output and status of a terminal. **Type:** Object @@ -1941,26 +1995,20 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - - Whether the client supports `terminal` authentication methods. +SessionId} required> + The session ID for this request. + + + The ID of the terminal to get output from. + -When `true`, the agent may include `terminal` entries in its authentication methods. +#### TerminalOutputResponse - - Default: `false` +Response containing the terminal output and exit status. - +**Type:** Object -## AuthEnvVar - -**UNSTABLE** - -This capability is not part of the spec yet, and may be removed or changed at any point. - -Describes a single environment variable for an `AuthMethodEnvVar` authentication method. - -**Type:** Object - -**Properties:** +**Properties:** The _meta property is reserved by ACP to allow clients and agents to attach additional @@ -1970,47 +2018,39 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - - Human-readable label for this variable, displayed in client UI. +TerminalExitStatus | null} > + Exit status if the command has completed. - - The environment variable name (e.g. `"OPENAI_API_KEY"`). + + The terminal output captured so far. - - Whether this variable is optional. - -Defaults to `false`. - - - Default: `false` - + + Whether the output was truncated due to byte limits. - - Whether this value is a secret (e.g. API key, token). -Clients should use a password-style input for secret vars. - -Defaults to `true`. - - Default: `true` + +### terminal/release - +Releases a terminal -## AuthMethod +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. -Describes an available authentication method. +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 `type` field acts as the discriminator in the serialized JSON form. -When no `type` is present, the method is treated as `agent`. +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. -**Type:** Union +See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals) - -**UNSTABLE** +#### ReleaseTerminalRequest -This capability is not part of the spec yet, and may be removed or changed at any point. +Request to release a terminal and free its resources. -User provides a key that the client passes to the agent as an environment variable. +**Type:** Object - +**Properties:** The _meta property is reserved by ACP to allow clients and agents to attach additional @@ -2020,36 +2060,20 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - - Optional description providing more details about this authentication method. - - - Unique identifier for this authentication method. - - - Optional link to a page where the user can obtain their credentials. - - - Human-readable name of the authentication method. - - - The discriminator value. Must be `"env_var"`. - -AuthEnvVar[]} required> - The environment variables the client should set. +SessionId} required> + The session ID for this request. - - + + The ID of the terminal to release. - -**UNSTABLE** +#### ReleaseTerminalResponse -This capability is not part of the spec yet, and may be removed or changed at any point. +Response to terminal/release method -Client runs an interactive terminal for the user to authenticate via a TUI. +**Type:** Object - +**Properties:** The _meta property is reserved by ACP to allow clients and agents to attach additional @@ -2059,34 +2083,21 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -"string"[]} > - Additional arguments to pass when running the agent binary for terminal auth. - - - Optional description providing more details about this authentication method. - - - Additional environment variables to set when running the agent binary for terminal auth. - - - Unique identifier for this authentication method. - - - Human-readable name of the authentication method. - - - The discriminator value. Must be `"terminal"`. - - - + +### terminal/wait_for_exit - -Agent handles authentication itself. +Waits for the terminal command to exit and return its exit status -This is the default when no `type` is specified. +See protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals) - +#### WaitForTerminalExitRequest + +Request to wait for a terminal command to exit. + +**Type:** Object + +**Properties:** The _meta property is reserved by ACP to allow clients and agents to attach additional @@ -2096,24 +2107,16 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - - Optional description providing more details about this authentication method. - - - Unique identifier for this authentication method. - - - Human-readable name of the authentication method. +SessionId} required> + The session ID for this request. - - + + The ID of the terminal to wait for. -## AuthMethodAgent - -Agent handles authentication itself. +#### WaitForTerminalExitResponse -This is the default authentication method type. +Response containing the exit status of a terminal command. **Type:** Object @@ -2127,25 +2130,59 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - - Optional description providing more details about this authentication method. - - - Unique identifier for this authentication method. + + The process exit code (may be null if terminated by signal). + + - Minimum: `0` + - - Human-readable name of the authentication method. + + The signal that terminated the process (may be null if exited normally). -## AuthMethodEnvVar +## 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 + +**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 +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) + +#### CancelRequestNotification **UNSTABLE** This capability is not part of the spec yet, and may be removed or changed at any point. -Environment variable authentication method. +Notification to cancel an ongoing request. -The user provides credentials that the client passes to the agent as environment variables. +See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation) **Type:** Object @@ -2159,31 +2196,17 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - - Optional description providing more details about this authentication method. - - - Unique identifier for this authentication method. - - - Optional link to a page where the user can obtain their credentials. - - - Human-readable name of the authentication method. - -AuthEnvVar[]} required> - The environment variables the client should set. +RequestId} required> + The ID of the request to cancel. -## AuthMethodTerminal +## AgentAuthCapabilities **UNSTABLE** This capability is not part of the spec yet, and may be removed or changed at any point. -Terminal-based authentication method. - -The client runs an interactive terminal for the user to authenticate via a TUI. +Authentication-related capabilities supported by the agent. **Type:** Object @@ -2197,25 +2220,21 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -"string"[]} > - Additional arguments to pass when running the agent binary for terminal auth. - - - Optional description providing more details about this authentication method. - - - Additional environment variables to set when running the agent binary for terminal auth. - - - Unique identifier for this authentication method. - - - Human-readable name of the authentication method. +LogoutCapabilities | null} > + Whether the agent supports the logout method. + +By supplying `\{\}` it means that the agent supports the logout method. + -## AvailableCommand +## AgentCapabilities -Information about a command. +Capabilities supported by the agent. + +Advertised during initialization to inform the client about +available features and content types. + +See protocol docs: [Agent Capabilities](https://agentclientprotocol.com/protocol/initialization#agent-capabilities) **Type:** Object @@ -2229,61 +2248,59 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - - Human-readable description of what the command does. - -AvailableCommandInput | null} > - Input for the command if required - - - Command name (e.g., `create_plan`, `research_codebase`). - +AgentAuthCapabilities} > + **UNSTABLE** -## AvailableCommandInput +This capability is not part of the spec yet, and may be removed or changed at any point. -The input specification for a command. +Authentication-related capabilities supported by the agent. -All text that was typed after the command name is provided as input. + - Default: `{}` -**Type:** Object + + + Whether the agent supports `session/load`. -**Properties:** + - Default: `false` - - 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. + +McpCapabilities} > + MCP capabilities supported by the agent. -See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + - Default: `{"http":false,"sse":false}` - - A hint to display when the input hasn't been provided yet - +NesCapabilities | null} > + **UNSTABLE** -## AvailableCommandsUpdate +This capability is not part of the spec yet, and may be removed or changed at any point. -Available commands are ready or have changed +NES (Next Edit Suggestions) capabilities supported by the agent. -**Type:** Object + +PositionEncodingKind | null} > + **UNSTABLE** -**Properties:** +This capability is not part of the spec yet, and may be removed or changed at any point. - - 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. +The position encoding selected by the agent from the client's supported encodings. -See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + +PromptCapabilities} > + Prompt capabilities supported by the agent. + + - Default: `{"audio":false,"embeddedContext":false,"image":false}` -AvailableCommand[]} required> - Commands the agent can execute +SessionCapabilities} > + + - Default: `{}` + -## BlobResourceContents +## Annotations -Binary resource contents. +Optional annotations for the client. The client can use annotations to inform how objects are used or displayed **Type:** Object @@ -2297,39 +2314,16 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - - - - - - - -## BooleanPropertySchema - -Schema for boolean properties in an elicitation form. - -**Type:** Object - -**Properties:** - - - Default value. +Role[] | null} > - - Human-readable description. + - - Optional title for the property. + -## ClientCapabilities - -Capabilities supported by the client. - -Advertised during initialization to inform the agent about -available features and methods. +## AudioContent -See protocol docs: [Client Capabilities](https://agentclientprotocol.com/protocol/initialization#client-capabilities) +Audio provided to or from an LLM. **Type:** Object @@ -2343,44 +2337,24 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -AuthCapabilities} > - **UNSTABLE** - -This capability is not part of the spec yet, and may be removed or changed at any point. - -Authentication capabilities supported by the client. -Determines which authentication method types the agent may include -in its `InitializeResponse`. - - - Default: `{"terminal":false}` - +Annotations | null} > -ElicitationCapabilities | null} > - **UNSTABLE** - -This capability is not part of the spec yet, and may be removed or changed at any point. - -Elicitation capabilities supported by the client. -Determines which elicitation modes the agent may use. - + -FileSystemCapabilities} > - File system capabilities supported by the client. -Determines which file operations the agent can request. - - - Default: `{"readTextFile":false,"writeTextFile":false}` - + - - Whether the Client support all `terminal/*` methods. - - Default: `false` +## AuthCapabilities - +**UNSTABLE** -## ConfigOptionUpdate +This capability is not part of the spec yet, and may be removed or changed at any point. -Session configuration options have been updated. +Authentication capabilities supported by the client. + +Advertised during initialization to inform the agent which authentication +method types the client can handle. This governs opt-in types that require +additional client-side support. **Type:** Object @@ -2394,13 +2368,22 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -SessionConfigOption[]} required> - The full set of configuration options and their current values. + + Whether the client supports `terminal` authentication methods. + +When `true`, the agent may include `terminal` entries in its authentication methods. + + - Default: `false` + -## Content +## AuthEnvVar -Standard content block (text, images, resources). +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Describes a single environment variable for an `AuthMethodEnvVar` authentication method. **Type:** Object @@ -2414,35 +2397,45 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -ContentBlock} required> - The actual content block. + + Human-readable label for this variable, displayed in client UI. + + The environment variable name (e.g. `"OPENAI_API_KEY"`). + + + Whether this variable is optional. -## ContentBlock +Defaults to `false`. -Content blocks represent displayable information in the Agent Client Protocol. + - Default: `false` -They provide a structured way to handle various types of user-facing content—whether -it's text from language models, images for analysis, or embedded resources for context. + + + Whether this value is a secret (e.g. API key, token). +Clients should use a password-style input for secret vars. -Content blocks appear in: +Defaults to `true`. -- User prompts sent via `session/prompt` -- Language model output streamed through `session/update` notifications -- Progress updates and results from tool calls + - Default: `true` -This structure is compatible with the Model Context Protocol (MCP), enabling -agents to seamlessly forward content from MCP tool outputs without transformation. + -See protocol docs: [Content](https://agentclientprotocol.com/protocol/content) +## AuthMethod + +Describes an available authentication method. + +The `type` field acts as the discriminator in the serialized JSON form. +When no `type` is present, the method is treated as `agent`. **Type:** Union - -Text content. May be plain text or formatted with Markdown. + +**UNSTABLE** -All agents MUST support text content blocks in prompts. -Clients SHOULD render this text as Markdown. +This capability is not part of the spec yet, and may be removed or changed at any point. + +User provides a key that the client passes to the agent as an environment variable. @@ -2454,21 +2447,34 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -Annotations | null} > + + Optional description providing more details about this authentication method. - + + Unique identifier for this authentication method. + + + Optional link to a page where the user can obtain their credentials. + + + Human-readable name of the authentication method. - The discriminator value. Must be `"text"`. + The discriminator value. Must be `"env_var"`. + +AuthEnvVar[]} required> + The environment variables the client should set. - -Images for visual context or analysis. + +**UNSTABLE** -Requires the `image` prompt capability when included in prompts. +This capability is not part of the spec yet, and may be removed or changed at any point. + +Client runs an interactive terminal for the user to authenticate via a TUI. @@ -2480,25 +2486,32 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -Annotations | null} > +"string"[]} > + Additional arguments to pass when running the agent binary for terminal auth. - + + Optional description providing more details about this authentication method. - + + Additional environment variables to set when running the agent binary for terminal auth. - - The discriminator value. Must be `"image"`. + + Unique identifier for this authentication method. - + + Human-readable name of the authentication method. + + + The discriminator value. Must be `"terminal"`. - -Audio data for transcription or analysis. + +Agent handles authentication itself. -Requires the `audio` prompt capability when included in prompts. +This is the default when no `type` is specified. @@ -2510,25 +2523,28 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -Annotations | null} > - - + + Optional description providing more details about this authentication method. - + + Unique identifier for this authentication method. - - The discriminator value. Must be `"audio"`. + + Human-readable name of the authentication method. - -References to resources that the agent can access. +## AuthMethodAgent -All agents MUST support resource links in prompts. +Agent handles authentication itself. - +This is the default authentication method type. + +**Type:** Object + +**Properties:** The _meta property is reserved by ACP to allow clients and agents to attach additional @@ -2537,36 +2553,30 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - -Annotations | null} > + Optional description providing more details about this authentication method. - + + Unique identifier for this authentication method. - - - - - - - The discriminator value. Must be `"resource_link"`. - - + Human-readable name of the authentication method. - - +## AuthMethodEnvVar - -Complete resource contents embedded directly in the message. +**UNSTABLE** -Preferred for including context as it avoids extra round-trips. +This capability is not part of the spec yet, and may be removed or changed at any point. -Requires the `embeddedContext` prompt capability when included in prompts. +Environment variable authentication method. - +The user provides credentials that the client passes to the agent as environment variables. + +**Type:** Object + +**Properties:** The _meta property is reserved by ACP to allow clients and agents to attach additional @@ -2576,20 +2586,31 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -Annotations | null} > + + Optional description providing more details about this authentication method. -EmbeddedResourceResource} required> + + Unique identifier for this authentication method. - - The discriminator value. Must be `"resource"`. + + Optional link to a page where the user can obtain their credentials. - - + + Human-readable name of the authentication method. + +AuthEnvVar[]} required> + The environment variables the client should set. -## ContentChunk +## AuthMethodTerminal -A streamed item of content +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Terminal-based authentication method. + +The client runs an interactive terminal for the user to authenticate via a TUI. **Type:** Object @@ -2603,46 +2624,73 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -ContentBlock} required> - A single item of content +"string"[]} > + Additional arguments to pass when running the agent binary for terminal auth. + + + Optional description providing more details about this authentication method. + + + Additional environment variables to set when running the agent binary for terminal auth. + + + Unique identifier for this authentication method. + + + Human-readable name of the authentication method. - - **UNSTABLE** -This capability is not part of the spec yet, and may be removed or changed at any point. +## AvailableCommand -A unique identifier for the message this chunk belongs to. +Information about a command. -All chunks belonging to the same message share the same `messageId`. -A change in `messageId` indicates a new message has started. -Both clients and agents MUST use UUID format for message IDs. +**Type:** Object - +**Properties:** -## Cost + + 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. -**UNSTABLE** +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -This capability is not part of the spec yet, and may be removed or changed at any point. + + + Human-readable description of what the command does. + +AvailableCommandInput | null} > + Input for the command if required + + + Command name (e.g., `create_plan`, `research_codebase`). + -Cost information for a session. +## AvailableCommandInput + +The input specification for a command. + +All text that was typed after the command name is provided as input. **Type:** Object **Properties:** - - Total cumulative cost for session. + + 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/extensibility) + - - ISO 4217 currency code (e.g., "USD", "EUR"). + + A hint to display when the input hasn't been provided yet -## CurrentModeUpdate - -The current mode of the session has changed +## AvailableCommandsUpdate -See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes) +Available commands are ready or have changed **Type:** Object @@ -2656,17 +2704,13 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -SessionModeId} required> - The ID of the current mode +AvailableCommand[]} required> + Commands the agent can execute -## Diff - -A diff representing file modifications. - -Shows changes to files in a format suitable for display in the client UI. +## BlobResourceContents -See protocol docs: [Content](https://agentclientprotocol.com/protocol/tool-calls#content) +Binary resource contents. **Type:** Object @@ -2680,88 +2724,106 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - - The new content after modification. + - - The original content (None for new files). + - - The file path being modified. + -## ElicitationAcceptAction - -**UNSTABLE** - -This capability is not part of the spec yet, and may be removed or changed at any point. +## BooleanPropertySchema -The user accepted the elicitation and provided content. +Schema for boolean properties in an elicitation form. **Type:** Object **Properties:** - - The user-provided content, if any, as an object matching the requested schema. + + Default value. + + + Human-readable description. + + + Optional title for the property. -## ElicitationAction +## ClientCapabilities -**UNSTABLE** +Capabilities supported by the client. -This capability is not part of the spec yet, and may be removed or changed at any point. +Advertised during initialization to inform the agent about +available features and methods. -The user's action in response to an elicitation. +See protocol docs: [Client Capabilities](https://agentclientprotocol.com/protocol/initialization#client-capabilities) -**Type:** Union +**Type:** Object - -The user accepted and provided content. +**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/extensibility) - - The discriminator value. Must be `"accept"`. - - - The user-provided content, if any, as an object matching the requested schema. +AuthCapabilities} > + **UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Authentication capabilities supported by the client. +Determines which authentication method types the agent may include +in its `InitializeResponse`. + + - Default: `{"terminal":false}` - +ElicitationCapabilities | null} > + **UNSTABLE** - -The user declined the elicitation. +This capability is not part of the spec yet, and may be removed or changed at any point. - +Elicitation capabilities supported by the client. +Determines which elicitation modes the agent may use. - - The discriminator value. Must be `"decline"`. +FileSystemCapabilities} > + File system capabilities supported by the client. +Determines which file operations the agent can request. + + - Default: `{"readTextFile":false,"writeTextFile":false}` - +ClientNesCapabilities | null} > + **UNSTABLE** - -The elicitation was cancelled. +This capability is not part of the spec yet, and may be removed or changed at any point. - +NES (Next Edit Suggestions) capabilities supported by the client. - - The discriminator value. Must be `"cancel"`. +PositionEncodingKind[]} > + **UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +The position encodings supported by the client, in order of preference. - + + Whether the Client support all `terminal/*` methods. -## ElicitationCapabilities + - Default: `false` -**UNSTABLE** + -This capability is not part of the spec yet, and may be removed or changed at any point. +## ClientNesCapabilities -Elicitation capabilities supported by the client. +NES capabilities advertised by the client during initialization. **Type:** Object @@ -2775,44 +2837,39 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -ElicitationFormCapabilities | null} > - Whether the client supports form-based elicitation. +NesJumpCapabilities | null} > + Whether the client supports the `jump` suggestion kind. -ElicitationUrlCapabilities | null} > - Whether the client supports URL-based elicitation. +NesRenameCapabilities | null} > + Whether the client supports the `rename` suggestion kind. + +NesSearchAndReplaceCapabilities | null} > + Whether the client supports the `searchAndReplace` suggestion kind. -## ElicitationContentValue +## ConfigOptionUpdate -**Type:** Union +Session configuration options have been updated. - - {""} - +**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/extensibility) - - {""} + +SessionConfigOption[]} required> + The full set of configuration options and their current values. -## ElicitationFormCapabilities - -**UNSTABLE** - -This capability is not part of the spec yet, and may be removed or changed at any point. +## Content -Form-based elicitation capabilities. +Standard content block (text, images, resources). **Type:** Object @@ -2826,206 +2883,618 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - -## ElicitationFormMode - -**UNSTABLE** - -This capability is not part of the spec yet, and may be removed or changed at any point. - -Form-based elicitation mode where the client renders a form from the provided schema. - -**Type:** Object - -**Properties:** - -ElicitationSchema} - required -> - A JSON Schema describing the form fields to present to the user. +ContentBlock} required> + The actual content block. -## ElicitationId - -**UNSTABLE** +## ContentBlock -This capability is not part of the spec yet, and may be removed or changed at any point. +Content blocks represent displayable information in the Agent Client Protocol. -Unique identifier for an elicitation. +They provide a structured way to handle various types of user-facing content—whether +it's text from language models, images for analysis, or embedded resources for context. -**Type:** `string` +Content blocks appear in: -## ElicitationPropertySchema +- User prompts sent via `session/prompt` +- Language model output streamed through `session/update` notifications +- Progress updates and results from tool calls -Property schema for elicitation form fields. +This structure is compatible with the Model Context Protocol (MCP), enabling +agents to seamlessly forward content from MCP tool outputs without transformation. -Each variant corresponds to a JSON Schema `"type"` value. -Single-select enums use the `String` variant with `enum` or `oneOf` set. -Multi-select enums use the `Array` variant. +See protocol docs: [Content](https://agentclientprotocol.com/protocol/content) **Type:** Union - -String property (or single-select enum when `enum`/`oneOf` is set). - - + +Text content. May be plain text or formatted with Markdown. - - Default value. - - - Human-readable description. - -<>"string"[] | null} > - Enum values for untitled single-select enums. - -StringFormat | null} > - String format. - - - Maximum string length. +All agents MUST support text content blocks in prompts. +Clients SHOULD render this text as Markdown. - - Minimum: `0` + - - - Minimum string length. + + 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. - - Minimum: `0` +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -EnumOption[] | null} > - Titled enum options for titled single-select enums. - - - Pattern the string must match. +Annotations | null} > - - Optional title for the property. + - The discriminator value. Must be `"string"`. + The discriminator value. Must be `"text"`. - -Number (floating-point) property. + +Images for visual context or analysis. + +Requires the `image` prompt capability when included in prompts. - - Default value. - - - Human-readable description. + + 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/extensibility) + - - Maximum value (inclusive). +Annotations | null} > - - Minimum value (inclusive). + - - Optional title for the property. + - The discriminator value. Must be `"number"`. + The discriminator value. Must be `"image"`. + + - -Integer property. + +Audio data for transcription or analysis. + +Requires the `audio` prompt capability when included in prompts. - - Default value. - - - Human-readable description. + + 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/extensibility) + - - Maximum value (inclusive). +Annotations | null} > - - Minimum value (inclusive). + - - Optional title for the property. + - The discriminator value. Must be `"integer"`. + The discriminator value. Must be `"audio"`. - -Boolean property. + +References to resources that the agent can access. + +All agents MUST support resource links in prompts. - - Default value. + + 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/extensibility) + - - Human-readable description. +Annotations | null} > - - Optional title for the property. + + + + + + + + + - The discriminator value. Must be `"boolean"`. + The discriminator value. Must be `"resource_link"`. + + - -Multi-select array property. + +Complete resource contents embedded directly in the message. - +Preferred for including context as it avoids extra round-trips. -<>"string"[] | null} > - Default selected values. - - - Human-readable description. - -MultiSelectItems} required> - The items definition describing allowed values. - - - Maximum number of items to select. +Requires the `embeddedContext` prompt capability when included in prompts. - - Minimum: `0` + - - - Minimum number of items to select. + + 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. - - Minimum: `0` +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - - Optional title for the property. +Annotations | null} > + +EmbeddedResourceResource} required> - The discriminator value. Must be `"array"`. + The discriminator value. Must be `"resource"`. -## ElicitationSchema +## ContentChunk -Type-safe elicitation schema for requesting structured user input. +A streamed item of content + +**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/extensibility) + + +ContentBlock} required> + A single item of content + + + **UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +A unique identifier for the message this chunk belongs to. + +All chunks belonging to the same message share the same `messageId`. +A change in `messageId` indicates a new message has started. +Both clients and agents MUST use UUID format for message IDs. + + + +## Cost + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Cost information for a session. + +**Type:** Object + +**Properties:** + + + Total cumulative cost for session. + + + ISO 4217 currency code (e.g., "USD", "EUR"). + + +## CurrentModeUpdate + +The current mode of the session has changed + +See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes) + +**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/extensibility) + + +SessionModeId} required> + The ID of the current mode + + +## Diff + +A diff representing file modifications. + +Shows changes to files in a format suitable for display in the client UI. + +See protocol docs: [Content](https://agentclientprotocol.com/protocol/tool-calls#content) + +**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/extensibility) + + + + The new content after modification. + + + The original content (None for new files). + + + The file path being modified. + + +## ElicitationAcceptAction + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +The user accepted the elicitation and provided content. + +**Type:** Object + +**Properties:** + + + The user-provided content, if any, as an object matching the requested schema. + + +## ElicitationAction + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +The user's action in response to an elicitation. + +**Type:** Union + + +The user accepted and provided content. + + + + + The discriminator value. Must be `"accept"`. + + + The user-provided content, if any, as an object matching the requested schema. + + + + + + +The user declined the elicitation. + + + + + The discriminator value. Must be `"decline"`. + + + + + + +The elicitation was cancelled. + + + + + The discriminator value. Must be `"cancel"`. + + + + + +## ElicitationCapabilities + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Elicitation capabilities supported by the client. + +**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/extensibility) + + +ElicitationFormCapabilities | null} > + Whether the client supports form-based elicitation. + +ElicitationUrlCapabilities | null} > + Whether the client supports URL-based elicitation. + + +## ElicitationContentValue + +**Type:** Union + + + {""} + + + + {""} + + + + {""} + + + + {""} + + + + {""} + + +## ElicitationFormCapabilities + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Form-based elicitation capabilities. + +**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/extensibility) + + + +## ElicitationFormMode + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Form-based elicitation mode where the client renders a form from the provided schema. + +**Type:** Object + +**Properties:** + +ElicitationSchema} + required +> + A JSON Schema describing the form fields to present to the user. + + +## ElicitationId + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Unique identifier for an elicitation. + +**Type:** `string` + +## ElicitationPropertySchema + +Property schema for elicitation form fields. + +Each variant corresponds to a JSON Schema `"type"` value. +Single-select enums use the `String` variant with `enum` or `oneOf` set. +Multi-select enums use the `Array` variant. + +**Type:** Union + + +String property (or single-select enum when `enum`/`oneOf` is set). + + + + + Default value. + + + Human-readable description. + +<>"string"[] | null} > + Enum values for untitled single-select enums. + +StringFormat | null} > + String format. + + + Maximum string length. + + - Minimum: `0` + + + + Minimum string length. + + - Minimum: `0` + + +EnumOption[] | null} > + Titled enum options for titled single-select enums. + + + Pattern the string must match. + + + Optional title for the property. + + + The discriminator value. Must be `"string"`. + + + + + + +Number (floating-point) property. + + + + + Default value. + + + Human-readable description. + + + Maximum value (inclusive). + + + Minimum value (inclusive). + + + Optional title for the property. + + + The discriminator value. Must be `"number"`. + + + + + + +Integer property. + + + + + Default value. + + + Human-readable description. + + + Maximum value (inclusive). + + + Minimum value (inclusive). + + + Optional title for the property. + + + The discriminator value. Must be `"integer"`. + + + + + + +Boolean property. + + + + + Default value. + + + Human-readable description. + + + Optional title for the property. + + + The discriminator value. Must be `"boolean"`. + + + + + + +Multi-select array property. + + + +<>"string"[] | null} > + Default selected values. + + + Human-readable description. + +MultiSelectItems} required> + The items definition describing allowed values. + + + Maximum number of items to select. + + - Minimum: `0` + + + + Minimum number of items to select. + + - Minimum: `0` + + + + Optional title for the property. + + + The discriminator value. Must be `"array"`. + + + + + +## ElicitationSchema + +Type-safe elicitation schema for requesting structured user input. This represents a JSON Schema object with primitive-typed properties, as required by the elicitation specification. @@ -3034,55 +3503,665 @@ as required by the elicitation specification. **Properties:** - - Optional description of what this schema represents. - - - Property definitions (must be primitive types). + + Optional description of what this schema represents. + + + Property definitions (must be primitive types). + + - Default: `{}` + + +<>"string"[] | null} > + List of required property names. + + + Optional title for the schema. + +ElicitationSchemaType} > + Type discriminator. Always `"object"`. + + - Default: `"object"` + + + +## ElicitationSchemaType + +Type discriminator for elicitation schemas. + +**Type:** Union + + + Object schema type. + + +## ElicitationStringType + +Items definition for untitled multi-select enum properties. + +**Type:** Union + + + String schema type. + + +## ElicitationUrlCapabilities + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +URL-based elicitation capabilities. + +**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/extensibility) + + + +## ElicitationUrlMode + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +URL-based elicitation mode where the client directs the user to a URL. + +**Type:** Object + +**Properties:** + +ElicitationId} + required +> + The unique identifier for this elicitation. + + + The URL to direct the user to. + + +## EmbeddedResource + +The contents of a resource, embedded into a prompt or tool call result. + +**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/extensibility) + + +Annotations | null} > + +EmbeddedResourceResource} required> + + +## EmbeddedResourceResource + +Resource content that can be embedded in a message. + +**Type:** Union + + +{""} + + + + + 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/extensibility) + + + + + + + + + + + + + +{""} + + + + + 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/extensibility) + + + + + + + + + + + + +## EnumOption + +A titled enum option with a const value and human-readable title. + +**Type:** Object + +**Properties:** + + + The constant value for this option. + + + Human-readable title for this option. + + +## EnvVariable + +An environment variable to set when launching an MCP server. + +**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/extensibility) + + + + The name of the environment variable. + + + The value to set for the environment variable. + + +## Error + +JSON-RPC error object. + +Represents an error that occurred during method execution, following the +JSON-RPC 2.0 error object specification with optional additional data. + +See protocol docs: [JSON-RPC Error Object](https://www.jsonrpc.org/specification#error_object) + +**Type:** Object + +**Properties:** + +ErrorCode} required> + A number indicating the error type that occurred. This must be an integer as + defined in the JSON-RPC specification. + + + Optional primitive or structured value that contains additional information + about the error. This may include debugging information or context-specific + details. + + + A string providing a short description of the error. The message should be + limited to a concise single sentence. + + +## ErrorCode + +Predefined error codes for common JSON-RPC and ACP-specific errors. + +These codes follow the JSON-RPC 2.0 specification for standard errors +and use the reserved range (-32000 to -32099) for protocol-specific errors. + +**Type:** Union + + + **Parse error**: Invalid JSON was received by the server. An error occurred on + the server while parsing the JSON text. + + + + **Invalid request**: The JSON sent is not a valid Request object. + + + + **Method not found**: The method does not exist or is not available. + + + + **Invalid params**: Invalid method parameter(s). + + + + **Internal error**: Internal JSON-RPC error. Reserved for + implementation-defined server 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. + + + + + **Authentication required**: Authentication is required before this operation + can be performed. + + + + **Resource not found**: A given resource, such as a file, was not found. + + + +**URL elicitation required**: **UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +The agent requires user input via a URL-based elicitation before it can proceed. + + + + + Other undefined error code. + + +## ExtNotification + +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) + +## ExtRequest + +Allows for sending 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) + +## ExtResponse + +Allows for sending an arbitrary response to an `ExtRequest` 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) + +## FileSystemCapabilities + +File system capabilities that a client may support. + +See protocol docs: [FileSystem](https://agentclientprotocol.com/protocol/initialization#filesystem) + +**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/extensibility) + + + + Whether the Client supports `fs/read_text_file` requests. + + - Default: `false` + + + + Whether the Client supports `fs/write_text_file` requests. + + - Default: `false` + + + +## HttpHeader + +An HTTP header to set when making requests to the MCP server. + +**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/extensibility) + + + + The name of the HTTP header. + + + The value to set for the HTTP header. + + +## ImageContent + +An image provided to or from an LLM. + +**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/extensibility) + + +Annotations | null} > + + + + + + + + +## Implementation + +Metadata about the implementation of the client or agent. +Describes the name and version of an MCP implementation, with an optional +title for UI representation. + +**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. - - Default: `{}` +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -<>"string"[] | null} > - List of required property names. + + Intended for programmatic or logical use, but can be used as a display +name fallback if title isn’t present. - Optional title for the schema. + Intended for UI and end-user contexts — optimized to be human-readable +and easily understood. + +If not provided, the name should be used for display. + + + + Version of the implementation. Can be displayed to the user or used +for debugging or metrics purposes. (e.g. "1.0.0"). -ElicitationSchemaType} > - Type discriminator. Always `"object"`. - - Default: `"object"` +## IntegerPropertySchema + +Schema for integer properties in an elicitation form. + +**Type:** Object + +**Properties:** + + + Default value. + + + Human-readable description. + + + Maximum value (inclusive). + + + Minimum value (inclusive). + + + Optional title for the property. + + +## LogoutCapabilities + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Logout capabilities supported by the agent. + +By supplying `\{\}` it means that the agent supports the logout method. + +**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/extensibility) -## ElicitationSchemaType +## McpCapabilities -Type discriminator for elicitation schemas. +MCP capabilities supported by the agent + +**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/extensibility) + + + + Agent supports `McpServer::Http`. + + - Default: `false` + + + + Agent supports `McpServer::Sse`. + + - Default: `false` + + + +## McpServer + +Configuration for connecting to an MCP (Model Context Protocol) server. + +MCP servers provide tools and context that the agent can use when +processing prompts. + +See protocol docs: [MCP Servers](https://agentclientprotocol.com/protocol/session-setup#mcp-servers) **Type:** Union - - Object schema type. + +HTTP transport configuration + +Only available when the Agent capabilities indicate `mcp_capabilities.http` is `true`. + + + + + 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/extensibility) + + +HttpHeader[]} required> + HTTP headers to set when making requests to the MCP server. + + + Human-readable name identifying this MCP server. + + + The discriminator value. Must be `"http"`. + + + URL to the MCP server. -## ElicitationStringType + + -Items definition for untitled multi-select enum properties. + +SSE transport configuration + +Only available when the Agent capabilities indicate `mcp_capabilities.sse` is `true`. + + + + + 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/extensibility) + + +HttpHeader[]} required> + HTTP headers to set when making requests to the MCP server. + + + Human-readable name identifying this MCP server. + + + The discriminator value. Must be `"sse"`. + + + URL to the MCP server. + + + + + + +Stdio transport configuration + +All Agents MUST support this transport. + + + + + 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/extensibility) + + +"string"[]} required> + Command-line arguments to pass to the MCP server. + + + Path to the MCP server executable. + +EnvVariable[]} required> + Environment variables to set when launching the MCP server. + + + Human-readable name identifying this MCP server. + + + + + +## McpServerHttp + +HTTP transport configuration for MCP. + +**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/extensibility) + + +HttpHeader[]} required> + HTTP headers to set when making requests to the MCP server. + + + Human-readable name identifying this MCP server. + + + URL to the MCP server. + + +## McpServerSse + +SSE transport configuration for MCP. + +**Type:** Object -**Type:** Union +**Properties:** - - String schema type. - + + 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. -## ElicitationUrlCapabilities +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -**UNSTABLE** + +HttpHeader[]} required> + HTTP headers to set when making requests to the MCP server. + + + Human-readable name identifying this MCP server. + + + URL to the MCP server. + -This capability is not part of the spec yet, and may be removed or changed at any point. +## McpServerStdio -URL-based elicitation capabilities. +Stdio transport configuration for MCP. **Type:** Object @@ -3096,33 +4175,36 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) +"string"[]} required> + Command-line arguments to pass to the MCP server. + + + Path to the MCP server executable. + +EnvVariable[]} required> + Environment variables to set when launching the MCP server. + + + Human-readable name identifying this MCP server. + -## ElicitationUrlMode +## ModelId **UNSTABLE** This capability is not part of the spec yet, and may be removed or changed at any point. -URL-based elicitation mode where the client directs the user to a URL. +A unique identifier for a model. -**Type:** Object +**Type:** `string` -**Properties:** +## ModelInfo -ElicitationId} - required -> - The unique identifier for this elicitation. - - - The URL to direct the user to. - +**UNSTABLE** -## EmbeddedResource +This capability is not part of the spec yet, and may be removed or changed at any point. -The contents of a resource, embedded into a prompt or tool call result. +Information about a selectable model. **Type:** Object @@ -3136,81 +4218,125 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -Annotations | null} > + + Optional description of the model. -EmbeddedResourceResource} required> +ModelId} required> + Unique identifier for the model. + + + Human-readable name of the model. -## EmbeddedResourceResource +## MultiSelectItems -Resource content that can be embedded in a message. +Items for a multi-select (array) property schema. **Type:** Union - -{""} + +Untitled multi-select items with plain string values. - - 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/extensibility) - + + "string" + [] + + } + required +> + Allowed enum values. - +ElicitationStringType} + required +> + Item type discriminator. Must be `"string"`. - + + - + + +Titled multi-select items with human-readable labels. + + + +EnumOption[]} + required +> + Titled enum options. - -{""} +## MultiSelectPropertySchema - +Schema for multi-select (array) properties in an elicitation form. - - 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. +**Type:** Object -See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) +**Properties:** +<>"string"[] | null} > + Default selected values. - + + Human-readable description. - +MultiSelectItems} required> + The items definition describing allowed values. - + + Maximum number of items to select. + + - Minimum: `0` + + + Minimum number of items to select. - + - Minimum: `0` + + + + Optional title for the property. -## EnumOption +## NesCapabilities -A titled enum option with a const value and human-readable title. +NES capabilities advertised by the agent during initialization. **Type:** Object **Properties:** - - The constant value for this option. + + 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/extensibility) + - - Human-readable title for this option. +NesContextCapabilities | null} > + Context the agent wants attached to each suggestion request. + +NesEventCapabilities | null} > + Events the agent wants to receive. -## EnvVariable +## NesContextCapabilities -An environment variable to set when launching an MCP server. +Context capabilities the agent wants attached to each suggestion request. **Type:** Object @@ -3224,132 +4350,129 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - - The name of the environment variable. +NesDiagnosticsCapabilities | null} > + Whether the agent wants diagnostics context. - - The value to set for the environment variable. +NesEditHistoryCapabilities | null} > + Whether the agent wants edit history context. + +NesOpenFilesCapabilities | null} > + Whether the agent wants open files context. + +NesRecentFilesCapabilities | null} > + Whether the agent wants recent files context. + +NesRelatedSnippetsCapabilities | null} > + Whether the agent wants related snippets context. + +NesUserActionsCapabilities | null} > + Whether the agent wants user actions context. -## Error - -JSON-RPC error object. - -Represents an error that occurred during method execution, following the -JSON-RPC 2.0 error object specification with optional additional data. +## NesDiagnostic -See protocol docs: [JSON-RPC Error Object](https://www.jsonrpc.org/specification#error_object) +A diagnostic (error, warning, etc.). **Type:** Object **Properties:** -ErrorCode} required> - A number indicating the error type that occurred. This must be an integer as - defined in the JSON-RPC specification. + + The diagnostic message. - - Optional primitive or structured value that contains additional information - about the error. This may include debugging information or context-specific - details. +Range} required> + The range of the diagnostic. - - A string providing a short description of the error. The message should be - limited to a concise single sentence. +NesDiagnosticSeverity} + required +> + The severity of the diagnostic. + + + The URI of the file containing the diagnostic. -## ErrorCode - -Predefined error codes for common JSON-RPC and ACP-specific errors. +## NesDiagnosticSeverity -These codes follow the JSON-RPC 2.0 specification for standard errors -and use the reserved range (-32000 to -32099) for protocol-specific errors. +Severity of a diagnostic. **Type:** Union - - **Parse error**: Invalid JSON was received by the server. An error occurred on - the server while parsing the JSON text. + + An error. - - **Invalid request**: The JSON sent is not a valid Request object. + + A warning. - - **Method not found**: The method does not exist or is not available. + + An informational message. - - **Invalid params**: Invalid method parameter(s). + + A hint. - - **Internal error**: Internal JSON-RPC error. Reserved for - implementation-defined server errors. - +## NesDiagnosticsCapabilities - -**Request cancelled**: **UNSTABLE** +Capabilities for diagnostics context. -This capability is not part of the spec yet, and may be removed or changed at any point. +**Type:** Object -Execution of the method was aborted either due to a cancellation request from the caller or -because of resource constraints or shutdown. +**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. - - **Authentication required**: Authentication is required before this operation - can be performed. - +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - - **Resource not found**: A given resource, such as a file, was not found. - -**URL elicitation required**: **UNSTABLE** - -This capability is not part of the spec yet, and may be removed or changed at any point. - -The agent requires user input via a URL-based elicitation before it can proceed. +## NesDocumentDidChangeCapabilities - +Capabilities for `document/didChange` events. - - Other undefined error code. - +**Type:** Object -## ExtNotification +**Properties:** -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. + + 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/extensibility) -## ExtRequest + +TextDocumentSyncKind} required> + The sync kind the agent wants: `"full"` or `"incremental"`. + -Allows for sending an arbitrary request that is not part of the ACP spec. -Extension methods provide a way to add custom functionality while maintaining -protocol compatibility. +## NesDocumentDidCloseCapabilities -See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) +Marker for `document/didClose` capability support. -## ExtResponse +**Type:** Object -Allows for sending an arbitrary response to an `ExtRequest` that is not part of the ACP spec. -Extension methods provide a way to add custom functionality while maintaining -protocol compatibility. +**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/extensibility) -## FileSystemCapabilities + -File system capabilities that a client may support. +## NesDocumentDidFocusCapabilities -See protocol docs: [FileSystem](https://agentclientprotocol.com/protocol/initialization#filesystem) +Marker for `document/didFocus` capability support. **Type:** Object @@ -3363,22 +4486,27 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - - Whether the Client supports `fs/read_text_file` requests. - - Default: `false` +## NesDocumentDidOpenCapabilities - - - Whether the Client supports `fs/write_text_file` requests. +Marker for `document/didOpen` capability support. - - Default: `false` +**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/extensibility) -## HttpHeader +## NesDocumentDidSaveCapabilities -An HTTP header to set when making requests to the MCP server. +Marker for `document/didSave` capability support. **Type:** Object @@ -3392,16 +4520,10 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - - The name of the HTTP header. - - - The value to set for the HTTP header. - -## ImageContent +## NesDocumentEventCapabilities -An image provided to or from an LLM. +Document event capabilities the agent wants to receive. **Type:** Object @@ -3415,20 +4537,25 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -Annotations | null} > +NesDocumentDidChangeCapabilities | null} > + Whether the agent wants `document/didChange` events, and the sync kind. - +NesDocumentDidCloseCapabilities | null} > + Whether the agent wants `document/didClose` events. - +NesDocumentDidFocusCapabilities | null} > + Whether the agent wants `document/didFocus` events. - +NesDocumentDidOpenCapabilities | null} > + Whether the agent wants `document/didOpen` events. + +NesDocumentDidSaveCapabilities | null} > + Whether the agent wants `document/didSave` events. -## Implementation +## NesEditHistoryCapabilities -Metadata about the implementation of the client or agent. -Describes the name and version of an MCP implementation, with an optional -title for UI representation. +Capabilities for edit history context. **Type:** Object @@ -3442,55 +4569,66 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - - Intended for programmatic or logical use, but can be used as a display -name fallback if title isn’t present. + + Maximum number of edit history entries the agent can use. + + - Minimum: `0` + - - Intended for UI and end-user contexts — optimized to be human-readable -and easily understood. -If not provided, the name should be used for display. +## NesEditHistoryEntry + +An entry in the edit history. + +**Type:** Object + +**Properties:** + + A diff representing the edit. - - Version of the implementation. Can be displayed to the user or used -for debugging or metrics purposes. (e.g. "1.0.0"). + + The URI of the edited file. -## IntegerPropertySchema +## NesEditSuggestion -Schema for integer properties in an elicitation form. +A text edit suggestion. **Type:** Object **Properties:** - - Default value. - - - Human-readable description. + + + Position + + | null + + } +> + Optional suggested cursor position after applying edits. - - Maximum value (inclusive). +NesTextEdit[]} + required +> + The text edits to apply. - - Minimum value (inclusive). + + Unique identifier for accept/reject tracking. - - Optional title for the property. + + The URI of the file to edit. -## LogoutCapabilities - -**UNSTABLE** - -This capability is not part of the spec yet, and may be removed or changed at any point. - -Logout capabilities supported by the agent. +## NesEventCapabilities -By supplying `\{\}` it means that the agent supports the logout method. +Event capabilities the agent can consume. **Type:** Object @@ -3504,53 +4642,41 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) +NesDocumentEventCapabilities | null} > + Document event capabilities. + -## McpCapabilities +## NesExcerpt -MCP capabilities supported by the agent +A code excerpt from a file. **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. + + The end line of the excerpt (zero-based). -See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + - Minimum: `0` - - Agent supports `McpServer::Http`. + + The start line of the excerpt (zero-based). - - Default: `false` + - Minimum: `0` - - Agent supports `McpServer::Sse`. - - - Default: `false` - + + The text content of the excerpt. -## McpServer - -Configuration for connecting to an MCP (Model Context Protocol) server. - -MCP servers provide tools and context that the agent can use when -processing prompts. - -See protocol docs: [MCP Servers](https://agentclientprotocol.com/protocol/session-setup#mcp-servers) - -**Type:** Union +## NesJumpCapabilities - -HTTP transport configuration +Marker for jump suggestion support. -Only available when the Agent capabilities indicate `mcp_capabilities.http` is `true`. +**Type:** Object - +**Properties:** The _meta property is reserved by ACP to allow clients and agents to attach additional @@ -3560,28 +4686,56 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -HttpHeader[]} required> - HTTP headers to set when making requests to the MCP server. + +## NesJumpSuggestion + +A jump-to-location suggestion. + +**Type:** Object + +**Properties:** + + + Unique identifier for accept/reject tracking. - - Human-readable name identifying this MCP server. +Position} required> + The target position within the file. - - The discriminator value. Must be `"http"`. + + The file to navigate to. - - URL to the MCP server. + +## NesOpenFile + +An open file in the editor. + +**Type:** Object + +**Properties:** + + + The language identifier. + + Timestamp in milliseconds since epoch of when the file was last focused. - + - Minimum: `0` + + + + The URI of the file. + +Range | null} > + The visible range in the editor, if any. - -SSE transport configuration +## NesOpenFilesCapabilities -Only available when the Agent capabilities indicate `mcp_capabilities.sse` is `true`. +Capabilities for open files context. - +**Type:** Object + +**Properties:** The _meta property is reserved by ACP to allow clients and agents to attach additional @@ -3591,28 +4745,32 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -HttpHeader[]} required> - HTTP headers to set when making requests to the MCP server. - - - Human-readable name identifying this MCP server. + +## NesRecentFile + +A recently accessed file. + +**Type:** Object + +**Properties:** + + + The language identifier. - - The discriminator value. Must be `"sse"`. + + The full text content of the file. - - URL to the MCP server. + + The URI of the file. - - +## NesRecentFilesCapabilities - -Stdio transport configuration +Capabilities for recent files context. -All Agents MUST support this transport. +**Type:** Object - +**Properties:** The _meta property is reserved by ACP to allow clients and agents to attach additional @@ -3622,25 +4780,57 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -"string"[]} required> - Command-line arguments to pass to the MCP server. + + Maximum number of recent files the agent can use. + + - Minimum: `0` + - - Path to the MCP server executable. + +## NesRejectReason + +The reason a suggestion was rejected. + +**Type:** Union + + + The user explicitly dismissed the suggestion. -EnvVariable[]} required> - Environment variables to set when launching the MCP server. + + + The suggestion was shown but the user continued editing without interacting. - - Human-readable name identifying this MCP server. + + + The suggestion was superseded by a newer suggestion. - + + The request was cancelled before the agent returned a response. -## McpServerHttp +## NesRelatedSnippet -HTTP transport configuration for MCP. +A related code snippet from a file. + +**Type:** Object + +**Properties:** + +NesExcerpt[]} + required +> + The code excerpts. + + + The URI of the file containing the snippets. + + +## NesRelatedSnippetsCapabilities + +Capabilities for related snippets context. **Type:** Object @@ -3650,23 +4840,14 @@ HTTP transport configuration for MCP. 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/extensibility) - - -HttpHeader[]} required> - HTTP headers to set when making requests to the MCP server. - - - Human-readable name identifying this MCP server. - - - URL to the MCP server. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + -## McpServerSse +## NesRenameCapabilities -SSE transport configuration for MCP. +Marker for rename suggestion support. **Type:** Object @@ -3680,19 +4861,49 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -HttpHeader[]} required> - HTTP headers to set when making requests to the MCP server. + +## NesRenameSuggestion + +A rename symbol suggestion. + +**Type:** Object + +**Properties:** + + + Unique identifier for accept/reject tracking. + + + The new name for the symbol. +Position} required> + The position of the symbol to rename. + + + The file URI containing the symbol. + + +## NesRepository + +Repository metadata for an NES session. + +**Type:** Object + +**Properties:** + - Human-readable name identifying this MCP server. + The repository name. - - URL to the MCP server. + + The repository owner. + + + The remote URL of the repository. -## McpServerStdio +## NesSearchAndReplaceCapabilities -Stdio transport configuration for MCP. +Marker for search and replace suggestion support. **Type:** Object @@ -3706,36 +4917,34 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) -"string"[]} required> - Command-line arguments to pass to the MCP server. - - - Path to the MCP server executable. - -EnvVariable[]} required> - Environment variables to set when launching the MCP server. - - - Human-readable name identifying this MCP server. - - -## ModelId - -**UNSTABLE** -This capability is not part of the spec yet, and may be removed or changed at any point. +## NesSearchAndReplaceSuggestion -A unique identifier for a model. +A search-and-replace suggestion. -**Type:** `string` +**Type:** Object -## ModelInfo +**Properties:** -**UNSTABLE** + + Unique identifier for accept/reject tracking. + + + Whether `search` is a regular expression. Defaults to `false`. + + + The replacement text. + + + The text or pattern to find. + + + The file URI to search within. + -This capability is not part of the spec yet, and may be removed or changed at any point. +## NesSuggestContext -Information about a selectable model. +Context attached to a suggestion request. **Type:** Object @@ -3749,97 +4958,219 @@ these keys. See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - - Optional description of the model. +NesDiagnostic[] | null} > + Current diagnostics (errors, warnings). -ModelId} required> - Unique identifier for the model. +NesEditHistoryEntry[] | null} > + Recent edit history. - - Human-readable name of the model. +NesOpenFile[] | null} > + Currently open files in the editor. + +NesRecentFile[] | null} > + Recently accessed files. + +NesRelatedSnippet[] | null} > + Related code snippets. + +NesUserAction[] | null} > + Recent user actions (typing, navigation, etc.). -## MultiSelectItems +## NesSuggestion -Items for a multi-select (array) property schema. +A suggestion returned by the agent. **Type:** Union - -Untitled multi-select items with plain string values. + +A text edit suggestion. - "string" - [] + + Position + + | null } - required > - Allowed enum values. + Optional suggested cursor position after applying edits. ElicitationStringType} + name="edits" + type={NesTextEdit[]} required > - Item type discriminator. Must be `"string"`. + The text edits to apply. + + + Unique identifier for accept/reject tracking. + + + The discriminator value. Must be `"edit"`. + + + The URI of the file to edit. - -Titled multi-select items with human-readable labels. + +A jump-to-location suggestion. -EnumOption[]} - required -> - Titled enum options. + + Unique identifier for accept/reject tracking. + + + The discriminator value. Must be `"jump"`. + +Position} required> + The target position within the file. + + + The file to navigate to. -## MultiSelectPropertySchema + +A rename symbol suggestion. -Schema for multi-select (array) properties in an elicitation form. + + + + Unique identifier for accept/reject tracking. + + + The discriminator value. Must be `"rename"`. + + + The new name for the symbol. + +Position} required> + The position of the symbol to rename. + + + The file URI containing the symbol. + + + + + + +A search-and-replace suggestion. + + + + + Unique identifier for accept/reject tracking. + + + Whether `search` is a regular expression. Defaults to `false`. + + + The discriminator value. Must be `"searchAndReplace"`. + + + The replacement text. + + + The text or pattern to find. + + + The file URI to search within. + + + + + +## NesTextEdit + +A text edit within a suggestion. **Type:** Object **Properties:** -<>"string"[] | null} > - Default selected values. + + The replacement text. - - Human-readable description. +Range} required> + The range to replace. -MultiSelectItems} required> - The items definition describing allowed values. + +## NesTriggerKind + +What triggered the suggestion request. + +**Type:** Union + + + Triggered by user typing or cursor movement. - - Maximum number of items to select. - - Minimum: `0` + + Triggered by a diagnostic appearing at or near the cursor. + + + Triggered by an explicit user action (keyboard shortcut). - - Minimum number of items to select. + +## NesUserAction + +A user action (typing, cursor movement, etc.). + +**Type:** Object + +**Properties:** + + + The kind of action (e.g., "insertChar", "cursorMovement"). + +Position} required> + The position where the action occurred. + + + Timestamp in milliseconds since epoch. - Minimum: `0` - - Optional title for the property. + + The URI of the file where the action occurred. + + +## NesUserActionsCapabilities + +Capabilities for user actions context. + +**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/extensibility) + + + + Maximum number of user actions the agent can use. + + - Minimum: `0` + ## NumberPropertySchema @@ -4026,6 +5357,49 @@ See protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/agent The task has been successfully completed. +## Position + +A zero-based position in a text document. + +The meaning of `character` depends on the negotiated position encoding. + +**Type:** Object + +**Properties:** + + + Zero-based character offset (encoding-dependent). + + - Minimum: `0` + + + + Zero-based line number. + + - Minimum: `0` + + + +## PositionEncodingKind + +The encoding used for character offsets in positions. + +Follows the same conventions as LSP 3.17. The default is UTF-16. + +**Type:** Union + + + Character offsets count UTF-16 code units. This is the default. + + + + Character offsets count Unicode code points. + + + + Character offsets count UTF-8 code units (bytes). + + ## PromptCapabilities Prompt capabilities supported by the agent in `session/prompt` requests. @@ -4089,6 +5463,21 @@ Non-breaking changes should be introduced via capabilities. | Minimum | `0` | | Maximum | `65535` | +## Range + +A range in a text document, expressed as start and end positions. + +**Type:** Object + +**Properties:** + +Position} required> + The end position (exclusive). + +Position} required> + The start position (inclusive). + + ## RequestId JSON RPC Request Id @@ -5300,6 +6689,49 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte +## TextDocumentContentChangeEvent + +A content change event for a document. + +When `range` is `None`, `text` is the full content of the document. +When `range` is `Some`, `text` replaces the given range. + +**Type:** Object + +**Properties:** + + + + Range + + | null + + } +> + The range of the document that changed. If `None`, the entire content is + replaced. + + + The new text for the range, or the full document content if `range` is `None`. + + +## TextDocumentSyncKind + +How the agent wants document changes delivered. + +**Type:** Union + + + Client sends the entire file content on each change. + + + + Client sends only the changed ranges. + + ## TextResourceContents Text-based resource contents. @@ -5769,3 +7201,18 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte - Minimum: `0` + +## WorkspaceFolder + +A workspace folder. + +**Type:** Object + +**Properties:** + + + The display name of the folder. + + + The URI of the folder. + diff --git a/docs/rfds/next-edit-suggestions.mdx b/docs/rfds/next-edit-suggestions.mdx index ece81a25..335ed747 100644 --- a/docs/rfds/next-edit-suggestions.mdx +++ b/docs/rfds/next-edit-suggestions.mdx @@ -29,11 +29,11 @@ The client inspects these declarations and provides only what was requested, min ### Capability advertisement -During `initialize`, the agent includes a `nes` field in its capabilities: +During `initialize`, the agent includes a `nes` field in `agentCapabilities`: ```json { - "capabilities": { + "agentCapabilities": { "nes": { "events": { "document": { @@ -69,26 +69,25 @@ All fields under `events` and `context` are optional — an agent advertises onl #### Client capabilities -The **client** advertises its own NES-related capabilities in the `initialize` request. Currently, the client can declare which well-known IDE actions it supports by listing their IDs. The agent reads these and may later include `"action"` kind suggestions that reference them. +The **client** advertises its own NES-related capabilities in the `initialize` request. The client declares which suggestion kinds it supports beyond the basic `edit` kind. Agents should only suggest kinds that the client has advertised. ```json { - "capabilities": { + "clientCapabilities": { "nes": { - "ideActions": { - "rename": {}, - "searchAndReplace": {} - } + "jump": {}, + "rename": {}, + "searchAndReplace": {} } } } ``` -Each entry in `ideActions` is the ID of a well-known action (see [Well-known IDE actions](#well-known-ide-actions) below). Agents should only suggest actions that the client has advertised. +Each entry corresponds to a suggestion kind (see [Suggestion kinds](#suggestion-kinds) below). If a kind is absent, the agent must not produce suggestions of that kind. ### Session lifecycle -If the `nes` capability is present, the client may call `nes/start` to begin an NES session. An NES session is **separate from and independent of** the ACP chat session — it has its own session ID, its own lifecycle, and its own stream of events and requests. A single ACP connection may have any number of active NES sessions alongside any number of chat sessions. The NES session is started and stopped independently via `nes/start`; it does not inherit state from, or share context with, chat sessions. +If the `nes` capability is present, the client may call `nes/start` to begin an NES session. An NES session is **separate from and independent of** the ACP chat session — it has its own session ID, its own lifecycle, and its own stream of events and requests. A single ACP connection may have any number of active NES sessions alongside any number of chat sessions. The NES session is started via `nes/start` and closed via `nes/close`; it does not inherit state from, or share context with, chat sessions. The agent can also use the existing `configOptions` mechanism to expose NES-related settings (model selection, debounce preferences, enabled/disabled state, etc.). @@ -106,16 +105,14 @@ Three encoding kinds are supported: - `"utf-32"` — character offsets count Unicode code points. - `"utf-8"` — character offsets count UTF-8 code units (bytes). -**Negotiation:** The client declares which encodings it supports in the `initialize` request via `general.positionEncodings`, listed in order of preference. The agent selects one from the client's list and declares it in its `initialize` response as `positionEncoding`. If the client omits `positionEncodings`, or the agent omits `positionEncoding` in its response, both sides default to `"utf-16"`. +**Negotiation:** The client may declare the position encodings it supports in the `initialize` request via `clientCapabilities.positionEncodings`, listed in order of preference. The agent selects one from the client's list and declares it in its `initialize` response as `agentCapabilities.positionEncoding`. If the client omits `positionEncodings`, or the agent omits `positionEncoding` in its response, both sides default to `"utf-16"`. Client `initialize` request (excerpt): ```json { - "capabilities": { - "general": { - "positionEncodings": ["utf-32", "utf-16"] - } + "clientCapabilities": { + "positionEncodings": ["utf-32", "utf-16"] } } ``` @@ -124,7 +121,7 @@ Agent `initialize` response (excerpt): ```json { - "capabilities": { + "agentCapabilities": { "nes": { ... }, "positionEncoding": "utf-32" } @@ -135,7 +132,7 @@ The negotiated encoding applies to all `Position` and `Range` values exchanged w ### Events -Events are fire-and-forget notifications from client to agent. The client sends them only if the corresponding key is present in the agent's advertised `events` capability (e.g. `nes.events.document` for NES). +Events are fire-and-forget notifications from client to agent. Every event is scoped to the NES session identified by the `sessionId` returned from `nes/start`. The client sends them only if the corresponding key is present in the agent's advertised `events` capability (e.g. `nes.events.document` for NES). #### `document/didOpen` @@ -146,6 +143,7 @@ Sent when a file is opened in the editor. "jsonrpc": "2.0", "method": "document/didOpen", "params": { + "sessionId": "session_abc123", "uri": "file:///path/to/file.rs", "languageId": "rust", "version": 1, @@ -168,6 +166,7 @@ Sent when a file is edited. Supports two sync modes declared by the agent: "jsonrpc": "2.0", "method": "document/didChange", "params": { + "sessionId": "session_abc123", "uri": "file:///path/to/file.rs", "version": 2, "contentChanges": [ @@ -190,6 +189,7 @@ Sent when a file is edited. Supports two sync modes declared by the agent: "jsonrpc": "2.0", "method": "document/didChange", "params": { + "sessionId": "session_abc123", "uri": "file:///path/to/file.rs", "version": 2, "contentChanges": [ @@ -210,6 +210,7 @@ Sent when a file is closed. "jsonrpc": "2.0", "method": "document/didClose", "params": { + "sessionId": "session_abc123", "uri": "file:///path/to/file.rs" } } @@ -224,6 +225,7 @@ Sent when a file is saved. "jsonrpc": "2.0", "method": "document/didSave", "params": { + "sessionId": "session_abc123", "uri": "file:///path/to/file.rs" } } @@ -238,6 +240,7 @@ Sent when a file becomes the active editor tab. Unlike `document/didOpen` (which "jsonrpc": "2.0", "method": "document/didFocus", "params": { + "sessionId": "session_abc123", "uri": "file:///path/to/file.rs", "version": 2, "position": { "line": 5, "character": 12 }, @@ -261,6 +264,7 @@ The client requests a suggestion by calling `nes/suggest`. Context fields are in "id": 42, "method": "nes/suggest", "params": { + "sessionId": "session_abc123", "uri": "file:///path/to/file.rs", "version": 2, "position": { "line": 5, "character": 12 }, @@ -299,15 +303,13 @@ The client requests a suggestion by calling `nes/suggest`. Context fields are in { "action": "insertChar", "uri": "file:///path/to/file.rs", - "line": 5, - "offset": 12, + "position": { "line": 5, "character": 12 }, "timestampMs": 1719400000000 }, { "action": "cursorMovement", "uri": "file:///path/to/file.rs", - "line": 10, - "offset": 0, + "position": { "line": 10, "character": 0 }, "timestampMs": 1719400001200 } ], @@ -354,7 +356,7 @@ The client requests a suggestion by calling `nes/suggest`. Context fields are in ### Suggestion response -A suggestion is one of three kinds: an **edit** (text changes), a **jump** (navigate to a different file), or an **action** (trigger an IDE action). +A suggestion is one of several kinds, each identified by the `kind` field. The `edit` kind is always supported; other kinds (`jump`, `rename`, `searchAndReplace`) require the client to advertise support in its capabilities. **Edit suggestion:** @@ -403,7 +405,7 @@ A suggestion is one of three kinds: an **edit** (text changes), a **jump** (navi } ``` -**Action suggestion:** +**Rename suggestion:** ```json { @@ -413,33 +415,47 @@ A suggestion is one of three kinds: an **edit** (text changes), a **jump** (navi "suggestions": [ { "id": "sugg_003", - "kind": "action", - "actionId": "rename", - "arguments": { - "uri": "file:///path/to/file.rs", - "position": { "line": 5, "character": 10 }, - "newName": "calculateTotal" - } + "kind": "rename", + "uri": "file:///path/to/file.rs", + "position": { "line": 5, "character": 10 }, + "newName": "calculateTotal" } ] } } ``` -Action suggestions reference an IDE action that the client previously advertised in its capabilities: +**Search-and-replace suggestion:** -- `actionId` — matches an `id` from the client's advertised `ideActions`. -- `arguments` — matches the parameter schema declared by the client for that action. +```json +{ + "jsonrpc": "2.0", + "id": 42, + "result": { + "suggestions": [ + { + "id": "sugg_004", + "kind": "searchAndReplace", + "uri": "file:///path/to/file.rs", + "search": "oldFunction", + "replace": "newFunction", + "isRegex": false + } + ] + } +} +``` -A response may contain a mix of edit, jump, and action suggestions. The client decides how to present them (e.g. inline ghost text for edits, a navigation hint for jumps). +A response may contain a mix of suggestion kinds. The client decides how to present them (e.g. inline ghost text for edits, a navigation hint for jumps). Agents must only include suggestion kinds that the client has advertised in its capabilities (except `edit`, which is always supported). Each suggestion contains: - `id` — unique identifier for accept/reject tracking. -- `kind` — `"edit"`, `"jump"`, or `"action"`. +- `kind` — the suggestion kind (see [Suggestion kinds](#suggestion-kinds) below). Edit suggestions additionally contain: +- `uri` — the file to edit. - `edits` — one or more text edits to apply. - `cursorPosition` — optional suggested cursor position after applying edits. @@ -448,10 +464,18 @@ Jump suggestions additionally contain: - `uri` — the file to navigate to. - `position` — the target position within that file. -Action suggestions additionally contain: +Rename suggestions additionally contain: + +- `uri` — the file URI containing the symbol. +- `position` — the position of the symbol to rename. +- `newName` — the new name for the symbol. -- `actionId` — the IDE action to perform (must match a client-advertised action `id`). -- `arguments` — action parameters matching the schema from the client's capability. +Search-and-replace suggestions additionally contain: + +- `uri` — the file URI to search within. Can be a folder, then operation is performed in all the files in this folder. +- `search` — the text or pattern to find. +- `replace` — the replacement text. +- `isRegex` (`boolean`, optional) — whether `search` is a regular expression. Defaults to `false`. ### Accept / Reject @@ -460,6 +484,7 @@ Action suggestions additionally contain: "jsonrpc": "2.0", "method": "nes/accept", "params": { + "sessionId": "session_abc123", "id": "sugg_001" } } @@ -470,6 +495,7 @@ Action suggestions additionally contain: "jsonrpc": "2.0", "method": "nes/reject", "params": { + "sessionId": "session_abc123", "id": "sugg_001", "reason": "rejected" } @@ -520,11 +546,13 @@ Response: "jsonrpc": "2.0", "id": 1, "result": { - "sessionId": "nes_abc123" + "sessionId": "session_abc123" } } ``` +The returned `sessionId` scopes all subsequent NES events, requests, and notifications for that session. + #### Error handling The agent may reject `nes/start` with an error. In particular, agents that require authentication may return an `auth_required` error: @@ -534,7 +562,7 @@ The agent may reject `nes/start` with an error. In particular, agents that requi "jsonrpc": "2.0", "id": 1, "error": { - "code": -32001, + "code": -32000, "message": "Authentication required", "data": { "reason": "auth_required" @@ -545,28 +573,41 @@ The agent may reject `nes/start` with an error. In particular, agents that requi Clients **must** be prepared to handle `auth_required` errors on `nes/start`. The recommended behavior is to prompt the user to authenticate (e.g. sign in or provide credentials) and retry the `nes/start` call after authentication succeeds. Clients should not silently ignore this error or assume NES is unavailable — the agent may be fully functional once the user authenticates. -### Well-known IDE actions +### NES session close -The following actions are well-known and have standardized parameter schemas. Clients that support these actions should use the IDs and parameter shapes defined here. +The client closes an NES session by calling `nes/close`. The agent **must** cancel any ongoing work related to the NES session and free up any resources associated with it. -**`rename`** — Rename a symbol across the workspace. +```json +{ + "jsonrpc": "2.0", + "id": 2, + "method": "nes/close", + "params": { + "sessionId": "session_abc123" + } +} +``` -Parameters: +Response: -- `uri` (`string`) — the file URI containing the symbol. -- `position` (`Position`) — the position of the symbol to rename. -- `newName` (`string`) — the new name for the symbol. +```json +{ + "jsonrpc": "2.0", + "id": 2, + "result": {} +} +``` -**`searchAndReplace`** — Search and replace text within a file. +### Suggestion kinds -Parameters: +The `kind` field in each suggestion identifies its type. The following kinds are defined: -- `uri` (`string`) — the file URI to search within. -- `search` (`string`) — the text or pattern to find. -- `replace` (`string`) — the replacement text. -- `isRegex` (`boolean`, optional) — whether `search` is a regular expression. Defaults to `false`. +- **`edit`** — A text edit suggestion. Always supported; does not require a client capability. +- **`jump`** — Navigate to a different file/position. Requires `jump` in client capabilities. +- **`rename`** — Rename a symbol across the workspace. Requires `rename` in client capabilities. +- **`searchAndReplace`** — Search and replace text within a file/folder. Requires `searchAndReplace` in client capabilities. -Additional well-known actions may be added to the protocol in the future. Agents should only suggest actions whose `id` matches an entry the client has advertised. +Additional suggestion kinds may be added to the protocol in the future. Agents must only produce suggestions whose `kind` the client has advertised (except `edit`, which is always supported). ### Config options diff --git a/schema/meta.unstable.json b/schema/meta.unstable.json index 6198214a..167bba2f 100644 --- a/schema/meta.unstable.json +++ b/schema/meta.unstable.json @@ -1,8 +1,18 @@ { "agentMethods": { "authenticate": "authenticate", + "document_did_change": "document/didChange", + "document_did_close": "document/didClose", + "document_did_focus": "document/didFocus", + "document_did_open": "document/didOpen", + "document_did_save": "document/didSave", "initialize": "initialize", "logout": "logout", + "nes_accept": "nes/accept", + "nes_close": "nes/close", + "nes_reject": "nes/reject", + "nes_start": "nes/start", + "nes_suggest": "nes/suggest", "session_cancel": "session/cancel", "session_close": "session/close", "session_fork": "session/fork", diff --git a/schema/schema.unstable.json b/schema/schema.unstable.json index b93adf5f..0a6fb847 100644 --- a/schema/schema.unstable.json +++ b/schema/schema.unstable.json @@ -1,5 +1,31 @@ { "$defs": { + "AcceptNesNotification": { + "description": "Notification sent when a suggestion is accepted.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + }, + "id": { + "description": "The ID of the accepted suggestion.", + "type": "string" + }, + "sessionId": { + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ], + "description": "The session ID for this notification." + } + }, + "required": ["sessionId", "id"], + "type": "object", + "x-method": "nes/accept", + "x-side": "agent" + }, "AgentAuthCapabilities": { "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAuthentication-related capabilities supported by the agent.", "properties": { @@ -56,6 +82,28 @@ }, "description": "MCP capabilities supported by the agent." }, + "nes": { + "anyOf": [ + { + "$ref": "#/$defs/NesCapabilities" + }, + { + "type": "null" + } + ], + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nNES (Next Edit Suggestions) capabilities supported by the agent." + }, + "positionEncoding": { + "anyOf": [ + { + "$ref": "#/$defs/PositionEncodingKind" + }, + { + "type": "null" + } + ], + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe position encoding selected by the agent from the client's supported encodings." + }, "promptCapabilities": { "allOf": [ { @@ -357,6 +405,30 @@ ], "title": "SetSessionModelResponse" }, + { + "allOf": [ + { + "$ref": "#/$defs/StartNesResponse" + } + ], + "title": "StartNesResponse" + }, + { + "allOf": [ + { + "$ref": "#/$defs/SuggestNesResponse" + } + ], + "title": "SuggestNesResponse" + }, + { + "allOf": [ + { + "$ref": "#/$defs/CloseNesResponse" + } + ], + "title": "CloseNesResponse" + }, { "allOf": [ { @@ -850,6 +922,24 @@ }, "description": "File system capabilities supported by the client.\nDetermines which file operations the agent can request." }, + "nes": { + "anyOf": [ + { + "$ref": "#/$defs/ClientNesCapabilities" + }, + { + "type": "null" + } + ], + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nNES (Next Edit Suggestions) capabilities supported by the client." + }, + "positionEncodings": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe position encodings supported by the client, in order of preference.", + "items": { + "$ref": "#/$defs/PositionEncodingKind" + }, + "type": "array" + }, "terminal": { "default": false, "description": "Whether the Client support all `terminal/*` methods.", @@ -858,6 +948,50 @@ }, "type": "object" }, + "ClientNesCapabilities": { + "description": "NES capabilities advertised by the client during initialization.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + }, + "jump": { + "anyOf": [ + { + "$ref": "#/$defs/NesJumpCapabilities" + }, + { + "type": "null" + } + ], + "description": "Whether the client supports the `jump` suggestion kind." + }, + "rename": { + "anyOf": [ + { + "$ref": "#/$defs/NesRenameCapabilities" + }, + { + "type": "null" + } + ], + "description": "Whether the client supports the `rename` suggestion kind." + }, + "searchAndReplace": { + "anyOf": [ + { + "$ref": "#/$defs/NesSearchAndReplaceCapabilities" + }, + { + "type": "null" + } + ], + "description": "Whether the client supports the `searchAndReplace` suggestion kind." + } + }, + "type": "object" + }, "ClientNotification": { "properties": { "method": { @@ -876,6 +1010,69 @@ "description": "Cancels ongoing operations for a session.\n\nThis is a notification sent by the client to cancel an ongoing prompt turn.\n\nUpon receiving this notification, the Agent SHOULD:\n- Stop all language model requests as soon as possible\n- Abort all tool call invocations in progress\n- Send any pending `session/update` notifications\n- Respond to the original `session/prompt` request with `StopReason::Cancelled`\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation)", "title": "CancelNotification" }, + { + "allOf": [ + { + "$ref": "#/$defs/DidOpenDocumentNotification" + } + ], + "description": "**UNSTABLE**\n\nNotification sent when a file is opened in the editor.", + "title": "DidOpenDocumentNotification" + }, + { + "allOf": [ + { + "$ref": "#/$defs/DidChangeDocumentNotification" + } + ], + "description": "**UNSTABLE**\n\nNotification sent when a file is edited.", + "title": "DidChangeDocumentNotification" + }, + { + "allOf": [ + { + "$ref": "#/$defs/DidCloseDocumentNotification" + } + ], + "description": "**UNSTABLE**\n\nNotification sent when a file is closed.", + "title": "DidCloseDocumentNotification" + }, + { + "allOf": [ + { + "$ref": "#/$defs/DidSaveDocumentNotification" + } + ], + "description": "**UNSTABLE**\n\nNotification sent when a file is saved.", + "title": "DidSaveDocumentNotification" + }, + { + "allOf": [ + { + "$ref": "#/$defs/DidFocusDocumentNotification" + } + ], + "description": "**UNSTABLE**\n\nNotification sent when a file becomes the active editor tab.", + "title": "DidFocusDocumentNotification" + }, + { + "allOf": [ + { + "$ref": "#/$defs/AcceptNesNotification" + } + ], + "description": "**UNSTABLE**\n\nNotification sent when a suggestion is accepted.", + "title": "AcceptNesNotification" + }, + { + "allOf": [ + { + "$ref": "#/$defs/RejectNesNotification" + } + ], + "description": "**UNSTABLE**\n\nNotification sent when a suggestion is rejected.", + "title": "RejectNesNotification" + }, { "allOf": [ { @@ -1027,6 +1224,33 @@ "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSelect a model for a given session.", "title": "SetSessionModelRequest" }, + { + "allOf": [ + { + "$ref": "#/$defs/StartNesRequest" + } + ], + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nStarts an NES session.", + "title": "StartNesRequest" + }, + { + "allOf": [ + { + "$ref": "#/$defs/SuggestNesRequest" + } + ], + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequests a code suggestion.", + "title": "SuggestNesRequest" + }, + { + "allOf": [ + { + "$ref": "#/$defs/CloseNesRequest" + } + ], + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCloses an active NES session and frees up any resources associated with it.\n\nThe agent must cancel any ongoing work and then free up any resources\nassociated with the NES session.", + "title": "CloseNesRequest" + }, { "allOf": [ { @@ -1162,6 +1386,41 @@ ], "x-docs-ignore": true }, + "CloseNesRequest": { + "description": "Request to close an NES session.\n\nThe agent **must** cancel any ongoing work related to the NES session\nand then free up any resources associated with the session.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + }, + "sessionId": { + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ], + "description": "The ID of the NES session to close." + } + }, + "required": ["sessionId"], + "type": "object", + "x-method": "nes/close", + "x-side": "agent" + }, + "CloseNesResponse": { + "description": "Response from closing an NES session.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + } + }, + "type": "object", + "x-method": "nes/close", + "x-side": "agent" + }, "CloseSessionRequest": { "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for closing an active session.\n\nIf supported, the agent **must** cancel any ongoing work related to the session\n(treat it as if `session/cancel` was called) and then free up any resources\nassociated with the session.\n\nOnly available if the Agent supports the `session.close` capability.", "properties": { @@ -1452,59 +1711,235 @@ "required": ["currentModeId"], "type": "object" }, - "Diff": { - "description": "A diff representing file modifications.\n\nShows changes to files in a format suitable for display in the client UI.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/tool-calls#content)", + "DidChangeDocumentNotification": { + "description": "Notification sent when a file is edited.", "properties": { "_meta": { "additionalProperties": true, "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"] }, - "newText": { - "description": "The new content after modification.", - "type": "string" + "contentChanges": { + "description": "The content changes.", + "items": { + "$ref": "#/$defs/TextDocumentContentChangeEvent" + }, + "type": "array" }, - "oldText": { - "description": "The original content (None for new files).", - "type": ["string", "null"] + "sessionId": { + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ], + "description": "The session ID for this notification." }, - "path": { - "description": "The file path being modified.", + "uri": { + "description": "The URI of the changed document.", "type": "string" + }, + "version": { + "description": "The new version number of the document.", + "format": "int64", + "type": "integer" } }, - "required": ["path", "newText"], - "type": "object" + "required": ["sessionId", "uri", "version", "contentChanges"], + "type": "object", + "x-method": "document/didChange", + "x-side": "agent" }, - "ElicitationAcceptAction": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe user accepted the elicitation and provided content.", + "DidCloseDocumentNotification": { + "description": "Notification sent when a file is closed.", "properties": { - "content": { - "additionalProperties": { - "$ref": "#/$defs/ElicitationContentValue" - }, - "description": "The user-provided content, if any, as an object matching the requested schema.", + "_meta": { + "additionalProperties": true, + "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"] + }, + "sessionId": { + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ], + "description": "The session ID for this notification." + }, + "uri": { + "description": "The URI of the closed document.", + "type": "string" } }, - "type": "object" + "required": ["sessionId", "uri"], + "type": "object", + "x-method": "document/didClose", + "x-side": "agent" }, - "ElicitationAction": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe user's action in response to an elicitation.", - "discriminator": { - "propertyName": "action" - }, - "oneOf": [ - { + "DidFocusDocumentNotification": { + "description": "Notification sent when a file becomes the active editor tab.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + }, + "position": { "allOf": [ { - "$ref": "#/$defs/ElicitationAcceptAction" + "$ref": "#/$defs/Position" } ], - "description": "The user accepted and provided content.", - "properties": { - "action": { - "const": "accept", + "description": "The current cursor position." + }, + "sessionId": { + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ], + "description": "The session ID for this notification." + }, + "uri": { + "description": "The URI of the focused document.", + "type": "string" + }, + "version": { + "description": "The version number of the document.", + "format": "int64", + "type": "integer" + }, + "visibleRange": { + "allOf": [ + { + "$ref": "#/$defs/Range" + } + ], + "description": "The portion of the file currently visible in the editor viewport." + } + }, + "required": ["sessionId", "uri", "version", "position", "visibleRange"], + "type": "object", + "x-method": "document/didFocus", + "x-side": "agent" + }, + "DidOpenDocumentNotification": { + "description": "Notification sent when a file is opened in the editor.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + }, + "languageId": { + "description": "The language identifier of the document (e.g., \"rust\", \"python\").", + "type": "string" + }, + "sessionId": { + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ], + "description": "The session ID for this notification." + }, + "text": { + "description": "The full text content of the document.", + "type": "string" + }, + "uri": { + "description": "The URI of the opened document.", + "type": "string" + }, + "version": { + "description": "The version number of the document.", + "format": "int64", + "type": "integer" + } + }, + "required": ["sessionId", "uri", "languageId", "version", "text"], + "type": "object", + "x-method": "document/didOpen", + "x-side": "agent" + }, + "DidSaveDocumentNotification": { + "description": "Notification sent when a file is saved.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + }, + "sessionId": { + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ], + "description": "The session ID for this notification." + }, + "uri": { + "description": "The URI of the saved document.", + "type": "string" + } + }, + "required": ["sessionId", "uri"], + "type": "object", + "x-method": "document/didSave", + "x-side": "agent" + }, + "Diff": { + "description": "A diff representing file modifications.\n\nShows changes to files in a format suitable for display in the client UI.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/tool-calls#content)", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + }, + "newText": { + "description": "The new content after modification.", + "type": "string" + }, + "oldText": { + "description": "The original content (None for new files).", + "type": ["string", "null"] + }, + "path": { + "description": "The file path being modified.", + "type": "string" + } + }, + "required": ["path", "newText"], + "type": "object" + }, + "ElicitationAcceptAction": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe user accepted the elicitation and provided content.", + "properties": { + "content": { + "additionalProperties": { + "$ref": "#/$defs/ElicitationContentValue" + }, + "description": "The user-provided content, if any, as an object matching the requested schema.", + "type": ["object", "null"] + } + }, + "type": "object" + }, + "ElicitationAction": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe user's action in response to an elicitation.", + "discriminator": { + "propertyName": "action" + }, + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/$defs/ElicitationAcceptAction" + } + ], + "description": "The user accepted and provided content.", + "properties": { + "action": { + "const": "accept", "type": "string" } }, @@ -2845,49 +3280,938 @@ "description": "Titled multi-select items with human-readable labels.", "title": "Titled" } - ], - "description": "Items for a multi-select (array) property schema." + ], + "description": "Items for a multi-select (array) property schema." + }, + "MultiSelectPropertySchema": { + "description": "Schema for multi-select (array) properties in an elicitation form.", + "properties": { + "default": { + "description": "Default selected values.", + "items": { + "type": "string" + }, + "type": ["array", "null"] + }, + "description": { + "description": "Human-readable description.", + "type": ["string", "null"] + }, + "items": { + "allOf": [ + { + "$ref": "#/$defs/MultiSelectItems" + } + ], + "description": "The items definition describing allowed values." + }, + "maxItems": { + "description": "Maximum number of items to select.", + "format": "uint64", + "minimum": 0, + "type": ["integer", "null"] + }, + "minItems": { + "description": "Minimum number of items to select.", + "format": "uint64", + "minimum": 0, + "type": ["integer", "null"] + }, + "title": { + "description": "Optional title for the property.", + "type": ["string", "null"] + } + }, + "required": ["items"], + "type": "object" + }, + "NesCapabilities": { + "description": "NES capabilities advertised by the agent during initialization.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + }, + "context": { + "anyOf": [ + { + "$ref": "#/$defs/NesContextCapabilities" + }, + { + "type": "null" + } + ], + "description": "Context the agent wants attached to each suggestion request." + }, + "events": { + "anyOf": [ + { + "$ref": "#/$defs/NesEventCapabilities" + }, + { + "type": "null" + } + ], + "description": "Events the agent wants to receive." + } + }, + "type": "object" + }, + "NesContextCapabilities": { + "description": "Context capabilities the agent wants attached to each suggestion request.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + }, + "diagnostics": { + "anyOf": [ + { + "$ref": "#/$defs/NesDiagnosticsCapabilities" + }, + { + "type": "null" + } + ], + "description": "Whether the agent wants diagnostics context." + }, + "editHistory": { + "anyOf": [ + { + "$ref": "#/$defs/NesEditHistoryCapabilities" + }, + { + "type": "null" + } + ], + "description": "Whether the agent wants edit history context." + }, + "openFiles": { + "anyOf": [ + { + "$ref": "#/$defs/NesOpenFilesCapabilities" + }, + { + "type": "null" + } + ], + "description": "Whether the agent wants open files context." + }, + "recentFiles": { + "anyOf": [ + { + "$ref": "#/$defs/NesRecentFilesCapabilities" + }, + { + "type": "null" + } + ], + "description": "Whether the agent wants recent files context." + }, + "relatedSnippets": { + "anyOf": [ + { + "$ref": "#/$defs/NesRelatedSnippetsCapabilities" + }, + { + "type": "null" + } + ], + "description": "Whether the agent wants related snippets context." + }, + "userActions": { + "anyOf": [ + { + "$ref": "#/$defs/NesUserActionsCapabilities" + }, + { + "type": "null" + } + ], + "description": "Whether the agent wants user actions context." + } + }, + "type": "object" + }, + "NesDiagnostic": { + "description": "A diagnostic (error, warning, etc.).", + "properties": { + "message": { + "description": "The diagnostic message.", + "type": "string" + }, + "range": { + "allOf": [ + { + "$ref": "#/$defs/Range" + } + ], + "description": "The range of the diagnostic." + }, + "severity": { + "allOf": [ + { + "$ref": "#/$defs/NesDiagnosticSeverity" + } + ], + "description": "The severity of the diagnostic." + }, + "uri": { + "description": "The URI of the file containing the diagnostic.", + "type": "string" + } + }, + "required": ["uri", "range", "severity", "message"], + "type": "object" + }, + "NesDiagnosticSeverity": { + "description": "Severity of a diagnostic.", + "oneOf": [ + { + "const": "error", + "description": "An error.", + "type": "string" + }, + { + "const": "warning", + "description": "A warning.", + "type": "string" + }, + { + "const": "information", + "description": "An informational message.", + "type": "string" + }, + { + "const": "hint", + "description": "A hint.", + "type": "string" + } + ] + }, + "NesDiagnosticsCapabilities": { + "description": "Capabilities for diagnostics context.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + } + }, + "type": "object" + }, + "NesDocumentDidChangeCapabilities": { + "description": "Capabilities for `document/didChange` events.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + }, + "syncKind": { + "allOf": [ + { + "$ref": "#/$defs/TextDocumentSyncKind" + } + ], + "description": "The sync kind the agent wants: `\"full\"` or `\"incremental\"`." + } + }, + "required": ["syncKind"], + "type": "object" + }, + "NesDocumentDidCloseCapabilities": { + "description": "Marker for `document/didClose` capability support.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + } + }, + "type": "object" + }, + "NesDocumentDidFocusCapabilities": { + "description": "Marker for `document/didFocus` capability support.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + } + }, + "type": "object" + }, + "NesDocumentDidOpenCapabilities": { + "description": "Marker for `document/didOpen` capability support.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + } + }, + "type": "object" + }, + "NesDocumentDidSaveCapabilities": { + "description": "Marker for `document/didSave` capability support.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + } + }, + "type": "object" + }, + "NesDocumentEventCapabilities": { + "description": "Document event capabilities the agent wants to receive.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + }, + "didChange": { + "anyOf": [ + { + "$ref": "#/$defs/NesDocumentDidChangeCapabilities" + }, + { + "type": "null" + } + ], + "description": "Whether the agent wants `document/didChange` events, and the sync kind." + }, + "didClose": { + "anyOf": [ + { + "$ref": "#/$defs/NesDocumentDidCloseCapabilities" + }, + { + "type": "null" + } + ], + "description": "Whether the agent wants `document/didClose` events." + }, + "didFocus": { + "anyOf": [ + { + "$ref": "#/$defs/NesDocumentDidFocusCapabilities" + }, + { + "type": "null" + } + ], + "description": "Whether the agent wants `document/didFocus` events." + }, + "didOpen": { + "anyOf": [ + { + "$ref": "#/$defs/NesDocumentDidOpenCapabilities" + }, + { + "type": "null" + } + ], + "description": "Whether the agent wants `document/didOpen` events." + }, + "didSave": { + "anyOf": [ + { + "$ref": "#/$defs/NesDocumentDidSaveCapabilities" + }, + { + "type": "null" + } + ], + "description": "Whether the agent wants `document/didSave` events." + } + }, + "type": "object" + }, + "NesEditHistoryCapabilities": { + "description": "Capabilities for edit history context.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + }, + "maxCount": { + "description": "Maximum number of edit history entries the agent can use.", + "format": "uint32", + "minimum": 0, + "type": ["integer", "null"] + } + }, + "type": "object" + }, + "NesEditHistoryEntry": { + "description": "An entry in the edit history.", + "properties": { + "diff": { + "description": "A diff representing the edit.", + "type": "string" + }, + "uri": { + "description": "The URI of the edited file.", + "type": "string" + } + }, + "required": ["uri", "diff"], + "type": "object" + }, + "NesEditSuggestion": { + "description": "A text edit suggestion.", + "properties": { + "cursorPosition": { + "anyOf": [ + { + "$ref": "#/$defs/Position" + }, + { + "type": "null" + } + ], + "description": "Optional suggested cursor position after applying edits." + }, + "edits": { + "description": "The text edits to apply.", + "items": { + "$ref": "#/$defs/NesTextEdit" + }, + "type": "array" + }, + "id": { + "description": "Unique identifier for accept/reject tracking.", + "type": "string" + }, + "uri": { + "description": "The URI of the file to edit.", + "type": "string" + } + }, + "required": ["id", "uri", "edits"], + "type": "object" + }, + "NesEventCapabilities": { + "description": "Event capabilities the agent can consume.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + }, + "document": { + "anyOf": [ + { + "$ref": "#/$defs/NesDocumentEventCapabilities" + }, + { + "type": "null" + } + ], + "description": "Document event capabilities." + } + }, + "type": "object" + }, + "NesExcerpt": { + "description": "A code excerpt from a file.", + "properties": { + "endLine": { + "description": "The end line of the excerpt (zero-based).", + "format": "uint32", + "minimum": 0, + "type": "integer" + }, + "startLine": { + "description": "The start line of the excerpt (zero-based).", + "format": "uint32", + "minimum": 0, + "type": "integer" + }, + "text": { + "description": "The text content of the excerpt.", + "type": "string" + } + }, + "required": ["startLine", "endLine", "text"], + "type": "object" + }, + "NesJumpCapabilities": { + "description": "Marker for jump suggestion support.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + } + }, + "type": "object" + }, + "NesJumpSuggestion": { + "description": "A jump-to-location suggestion.", + "properties": { + "id": { + "description": "Unique identifier for accept/reject tracking.", + "type": "string" + }, + "position": { + "allOf": [ + { + "$ref": "#/$defs/Position" + } + ], + "description": "The target position within the file." + }, + "uri": { + "description": "The file to navigate to.", + "type": "string" + } + }, + "required": ["id", "uri", "position"], + "type": "object" + }, + "NesOpenFile": { + "description": "An open file in the editor.", + "properties": { + "languageId": { + "description": "The language identifier.", + "type": "string" + }, + "lastFocusedMs": { + "description": "Timestamp in milliseconds since epoch of when the file was last focused.", + "format": "uint64", + "minimum": 0, + "type": ["integer", "null"] + }, + "uri": { + "description": "The URI of the file.", + "type": "string" + }, + "visibleRange": { + "anyOf": [ + { + "$ref": "#/$defs/Range" + }, + { + "type": "null" + } + ], + "description": "The visible range in the editor, if any." + } + }, + "required": ["uri", "languageId"], + "type": "object" + }, + "NesOpenFilesCapabilities": { + "description": "Capabilities for open files context.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + } + }, + "type": "object" + }, + "NesRecentFile": { + "description": "A recently accessed file.", + "properties": { + "languageId": { + "description": "The language identifier.", + "type": "string" + }, + "text": { + "description": "The full text content of the file.", + "type": "string" + }, + "uri": { + "description": "The URI of the file.", + "type": "string" + } + }, + "required": ["uri", "languageId", "text"], + "type": "object" + }, + "NesRecentFilesCapabilities": { + "description": "Capabilities for recent files context.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + }, + "maxCount": { + "description": "Maximum number of recent files the agent can use.", + "format": "uint32", + "minimum": 0, + "type": ["integer", "null"] + } + }, + "type": "object" + }, + "NesRejectReason": { + "description": "The reason a suggestion was rejected.", + "oneOf": [ + { + "const": "rejected", + "description": "The user explicitly dismissed the suggestion.", + "type": "string" + }, + { + "const": "ignored", + "description": "The suggestion was shown but the user continued editing without interacting.", + "type": "string" + }, + { + "const": "replaced", + "description": "The suggestion was superseded by a newer suggestion.", + "type": "string" + }, + { + "const": "cancelled", + "description": "The request was cancelled before the agent returned a response.", + "type": "string" + } + ] + }, + "NesRelatedSnippet": { + "description": "A related code snippet from a file.", + "properties": { + "excerpts": { + "description": "The code excerpts.", + "items": { + "$ref": "#/$defs/NesExcerpt" + }, + "type": "array" + }, + "uri": { + "description": "The URI of the file containing the snippets.", + "type": "string" + } + }, + "required": ["uri", "excerpts"], + "type": "object" + }, + "NesRelatedSnippetsCapabilities": { + "description": "Capabilities for related snippets context.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + } + }, + "type": "object" + }, + "NesRenameCapabilities": { + "description": "Marker for rename suggestion support.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + } + }, + "type": "object" + }, + "NesRenameSuggestion": { + "description": "A rename symbol suggestion.", + "properties": { + "id": { + "description": "Unique identifier for accept/reject tracking.", + "type": "string" + }, + "newName": { + "description": "The new name for the symbol.", + "type": "string" + }, + "position": { + "allOf": [ + { + "$ref": "#/$defs/Position" + } + ], + "description": "The position of the symbol to rename." + }, + "uri": { + "description": "The file URI containing the symbol.", + "type": "string" + } + }, + "required": ["id", "uri", "position", "newName"], + "type": "object" + }, + "NesRepository": { + "description": "Repository metadata for an NES session.", + "properties": { + "name": { + "description": "The repository name.", + "type": "string" + }, + "owner": { + "description": "The repository owner.", + "type": "string" + }, + "remoteUrl": { + "description": "The remote URL of the repository.", + "type": "string" + } + }, + "required": ["name", "owner", "remoteUrl"], + "type": "object" + }, + "NesSearchAndReplaceCapabilities": { + "description": "Marker for search and replace suggestion support.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + } + }, + "type": "object" + }, + "NesSearchAndReplaceSuggestion": { + "description": "A search-and-replace suggestion.", + "properties": { + "id": { + "description": "Unique identifier for accept/reject tracking.", + "type": "string" + }, + "isRegex": { + "description": "Whether `search` is a regular expression. Defaults to `false`.", + "type": ["boolean", "null"] + }, + "replace": { + "description": "The replacement text.", + "type": "string" + }, + "search": { + "description": "The text or pattern to find.", + "type": "string" + }, + "uri": { + "description": "The file URI to search within.", + "type": "string" + } + }, + "required": ["id", "uri", "search", "replace"], + "type": "object" + }, + "NesSuggestContext": { + "description": "Context attached to a suggestion request.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + }, + "diagnostics": { + "description": "Current diagnostics (errors, warnings).", + "items": { + "$ref": "#/$defs/NesDiagnostic" + }, + "type": ["array", "null"] + }, + "editHistory": { + "description": "Recent edit history.", + "items": { + "$ref": "#/$defs/NesEditHistoryEntry" + }, + "type": ["array", "null"] + }, + "openFiles": { + "description": "Currently open files in the editor.", + "items": { + "$ref": "#/$defs/NesOpenFile" + }, + "type": ["array", "null"] + }, + "recentFiles": { + "description": "Recently accessed files.", + "items": { + "$ref": "#/$defs/NesRecentFile" + }, + "type": ["array", "null"] + }, + "relatedSnippets": { + "description": "Related code snippets.", + "items": { + "$ref": "#/$defs/NesRelatedSnippet" + }, + "type": ["array", "null"] + }, + "userActions": { + "description": "Recent user actions (typing, navigation, etc.).", + "items": { + "$ref": "#/$defs/NesUserAction" + }, + "type": ["array", "null"] + } + }, + "type": "object" + }, + "NesSuggestion": { + "description": "A suggestion returned by the agent.", + "discriminator": { + "propertyName": "kind" + }, + "oneOf": [ + { + "allOf": [ + { + "$ref": "#/$defs/NesEditSuggestion" + } + ], + "description": "A text edit suggestion.", + "properties": { + "kind": { + "const": "edit", + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "allOf": [ + { + "$ref": "#/$defs/NesJumpSuggestion" + } + ], + "description": "A jump-to-location suggestion.", + "properties": { + "kind": { + "const": "jump", + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "allOf": [ + { + "$ref": "#/$defs/NesRenameSuggestion" + } + ], + "description": "A rename symbol suggestion.", + "properties": { + "kind": { + "const": "rename", + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + }, + { + "allOf": [ + { + "$ref": "#/$defs/NesSearchAndReplaceSuggestion" + } + ], + "description": "A search-and-replace suggestion.", + "properties": { + "kind": { + "const": "searchAndReplace", + "type": "string" + } + }, + "required": ["kind"], + "type": "object" + } + ] + }, + "NesTextEdit": { + "description": "A text edit within a suggestion.", + "properties": { + "newText": { + "description": "The replacement text.", + "type": "string" + }, + "range": { + "allOf": [ + { + "$ref": "#/$defs/Range" + } + ], + "description": "The range to replace." + } + }, + "required": ["range", "newText"], + "type": "object" + }, + "NesTriggerKind": { + "description": "What triggered the suggestion request.", + "oneOf": [ + { + "const": "automatic", + "description": "Triggered by user typing or cursor movement.", + "type": "string" + }, + { + "const": "diagnostic", + "description": "Triggered by a diagnostic appearing at or near the cursor.", + "type": "string" + }, + { + "const": "manual", + "description": "Triggered by an explicit user action (keyboard shortcut).", + "type": "string" + } + ] }, - "MultiSelectPropertySchema": { - "description": "Schema for multi-select (array) properties in an elicitation form.", + "NesUserAction": { + "description": "A user action (typing, cursor movement, etc.).", "properties": { - "default": { - "description": "Default selected values.", - "items": { - "type": "string" - }, - "type": ["array", "null"] - }, - "description": { - "description": "Human-readable description.", - "type": ["string", "null"] + "action": { + "description": "The kind of action (e.g., \"insertChar\", \"cursorMovement\").", + "type": "string" }, - "items": { + "position": { "allOf": [ { - "$ref": "#/$defs/MultiSelectItems" + "$ref": "#/$defs/Position" } ], - "description": "The items definition describing allowed values." + "description": "The position where the action occurred." }, - "maxItems": { - "description": "Maximum number of items to select.", + "timestampMs": { + "description": "Timestamp in milliseconds since epoch.", "format": "uint64", "minimum": 0, - "type": ["integer", "null"] + "type": "integer" }, - "minItems": { - "description": "Minimum number of items to select.", - "format": "uint64", + "uri": { + "description": "The URI of the file where the action occurred.", + "type": "string" + } + }, + "required": ["action", "uri", "position", "timestampMs"], + "type": "object" + }, + "NesUserActionsCapabilities": { + "description": "Capabilities for user actions context.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + }, + "maxCount": { + "description": "Maximum number of user actions the agent can use.", + "format": "uint32", "minimum": 0, "type": ["integer", "null"] - }, - "title": { - "description": "Optional title for the property.", - "type": ["string", "null"] } }, - "required": ["items"], "type": "object" }, "NewSessionRequest": { @@ -3154,6 +4478,45 @@ } ] }, + "Position": { + "description": "A zero-based position in a text document.\n\nThe meaning of `character` depends on the negotiated position encoding.", + "properties": { + "character": { + "description": "Zero-based character offset (encoding-dependent).", + "format": "uint32", + "minimum": 0, + "type": "integer" + }, + "line": { + "description": "Zero-based line number.", + "format": "uint32", + "minimum": 0, + "type": "integer" + } + }, + "required": ["line", "character"], + "type": "object" + }, + "PositionEncodingKind": { + "description": "The encoding used for character offsets in positions.\n\nFollows the same conventions as LSP 3.17. The default is UTF-16.", + "oneOf": [ + { + "const": "utf-16", + "description": "Character offsets count UTF-16 code units. This is the default.", + "type": "string" + }, + { + "const": "utf-32", + "description": "Character offsets count Unicode code points.", + "type": "string" + }, + { + "const": "utf-8", + "description": "Character offsets count UTF-8 code units (bytes).", + "type": "string" + } + ] + }, "PromptCapabilities": { "description": "Prompt capabilities supported by the agent in `session/prompt` requests.\n\nBaseline agent functionality requires support for [`ContentBlock::Text`]\nand [`ContentBlock::ResourceLink`] in prompt requests.\n\nOther variants must be explicitly opted in to.\nCapabilities for different types of content in prompt requests.\n\nIndicates which content types beyond the baseline (text and resource links)\nthe agent can process.\n\nSee protocol docs: [Prompt Capabilities](https://agentclientprotocol.com/protocol/initialization#prompt-capabilities)", "properties": { @@ -3257,6 +4620,29 @@ "minimum": 0, "type": "integer" }, + "Range": { + "description": "A range in a text document, expressed as start and end positions.", + "properties": { + "end": { + "allOf": [ + { + "$ref": "#/$defs/Position" + } + ], + "description": "The end position (exclusive)." + }, + "start": { + "allOf": [ + { + "$ref": "#/$defs/Position" + } + ], + "description": "The start position (inclusive)." + } + }, + "required": ["start", "end"], + "type": "object" + }, "ReadTextFileRequest": { "description": "Request to read content from a text file.\n\nOnly available if the client supports the `fs.readTextFile` capability.", "properties": { @@ -3312,6 +4698,43 @@ "x-method": "fs/read_text_file", "x-side": "client" }, + "RejectNesNotification": { + "description": "Notification sent when a suggestion is rejected.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + }, + "id": { + "description": "The ID of the rejected suggestion.", + "type": "string" + }, + "reason": { + "anyOf": [ + { + "$ref": "#/$defs/NesRejectReason" + }, + { + "type": "null" + } + ], + "description": "The reason for rejection." + }, + "sessionId": { + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ], + "description": "The session ID for this notification." + } + }, + "required": ["sessionId", "id"], + "type": "object", + "x-method": "nes/reject", + "x-side": "agent" + }, "ReleaseTerminalRequest": { "description": "Request to release a terminal and free its resources.", "properties": { @@ -4484,6 +5907,63 @@ "x-method": "session/set_model", "x-side": "agent" }, + "StartNesRequest": { + "description": "Request to start an NES session.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + }, + "repository": { + "anyOf": [ + { + "$ref": "#/$defs/NesRepository" + }, + { + "type": "null" + } + ], + "description": "Repository metadata, if the workspace is a git repository." + }, + "workspaceFolders": { + "description": "The workspace folders.", + "items": { + "$ref": "#/$defs/WorkspaceFolder" + }, + "type": ["array", "null"] + }, + "workspaceUri": { + "description": "The root URI of the workspace.", + "type": ["string", "null"] + } + }, + "type": "object", + "x-method": "nes/start", + "x-side": "agent" + }, + "StartNesResponse": { + "description": "Response to `nes/start`.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + }, + "sessionId": { + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ], + "description": "The session ID for the newly started NES session." + } + }, + "required": ["sessionId"], + "type": "object", + "x-method": "nes/start", + "x-side": "agent" + }, "StopReason": { "description": "Reasons why an agent stops processing a prompt turn.\n\nSee protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/prompt-turn#stop-reasons)", "oneOf": [ @@ -4598,6 +6078,96 @@ }, "type": "object" }, + "SuggestNesRequest": { + "description": "Request for a code suggestion.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + }, + "context": { + "anyOf": [ + { + "$ref": "#/$defs/NesSuggestContext" + }, + { + "type": "null" + } + ], + "description": "Context for the suggestion, included based on agent capabilities." + }, + "position": { + "allOf": [ + { + "$ref": "#/$defs/Position" + } + ], + "description": "The current cursor position." + }, + "selection": { + "anyOf": [ + { + "$ref": "#/$defs/Range" + }, + { + "type": "null" + } + ], + "description": "The current text selection range, if any." + }, + "sessionId": { + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ], + "description": "The session ID for this request." + }, + "triggerKind": { + "allOf": [ + { + "$ref": "#/$defs/NesTriggerKind" + } + ], + "description": "What triggered this suggestion request." + }, + "uri": { + "description": "The URI of the document to suggest for.", + "type": "string" + }, + "version": { + "description": "The version number of the document.", + "format": "int64", + "type": "integer" + } + }, + "required": ["sessionId", "uri", "version", "position", "triggerKind"], + "type": "object", + "x-method": "nes/suggest", + "x-side": "agent" + }, + "SuggestNesResponse": { + "description": "Response to `nes/suggest`.", + "properties": { + "_meta": { + "additionalProperties": true, + "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"] + }, + "suggestions": { + "description": "The list of suggestions.", + "items": { + "$ref": "#/$defs/NesSuggestion" + }, + "type": "array" + } + }, + "required": ["suggestions"], + "type": "object", + "x-method": "nes/suggest", + "x-side": "agent" + }, "Terminal": { "description": "Embed a terminal created with `terminal/create` by its id.\n\nThe terminal must be added before calling `terminal/release`.\n\nSee protocol docs: [Terminal](https://agentclientprotocol.com/protocol/terminals)", "properties": { @@ -4718,6 +6288,43 @@ "required": ["text"], "type": "object" }, + "TextDocumentContentChangeEvent": { + "description": "A content change event for a document.\n\nWhen `range` is `None`, `text` is the full content of the document.\nWhen `range` is `Some`, `text` replaces the given range.", + "properties": { + "range": { + "anyOf": [ + { + "$ref": "#/$defs/Range" + }, + { + "type": "null" + } + ], + "description": "The range of the document that changed. If `None`, the entire content is replaced." + }, + "text": { + "description": "The new text for the range, or the full document content if `range` is `None`.", + "type": "string" + } + }, + "required": ["text"], + "type": "object" + }, + "TextDocumentSyncKind": { + "description": "How the agent wants document changes delivered.", + "oneOf": [ + { + "const": "full", + "description": "Client sends the entire file content on each change.", + "type": "string" + }, + { + "const": "incremental", + "description": "Client sends only the changed ranges.", + "type": "string" + } + ] + }, "TextResourceContents": { "description": "Text-based resource contents.", "properties": { @@ -5206,6 +6813,21 @@ "x-method": "terminal/wait_for_exit", "x-side": "client" }, + "WorkspaceFolder": { + "description": "A workspace folder.", + "properties": { + "name": { + "description": "The display name of the folder.", + "type": "string" + }, + "uri": { + "description": "The URI of the folder.", + "type": "string" + } + }, + "required": ["uri", "name"], + "type": "object" + }, "WriteTextFileRequest": { "description": "Request to write content to a text file.\n\nOnly available if the client supports the `fs.writeTextFile` capability.", "properties": { diff --git a/src/agent.rs b/src/agent.rs index d67a6698..8166c4a6 100644 --- a/src/agent.rs +++ b/src/agent.rs @@ -17,6 +17,22 @@ use crate::{ ProtocolVersion, SessionId, }; +#[cfg(feature = "unstable_nes")] +use crate::{ + AcceptNesNotification, CloseNesRequest, CloseNesResponse, DidChangeDocumentNotification, + DidCloseDocumentNotification, DidFocusDocumentNotification, DidOpenDocumentNotification, + DidSaveDocumentNotification, NesCapabilities, PositionEncodingKind, RejectNesNotification, + StartNesRequest, StartNesResponse, SuggestNesRequest, SuggestNesResponse, +}; + +#[cfg(feature = "unstable_nes")] +use crate::nes::{ + DOCUMENT_DID_CHANGE_METHOD_NAME, DOCUMENT_DID_CLOSE_METHOD_NAME, + DOCUMENT_DID_FOCUS_METHOD_NAME, DOCUMENT_DID_OPEN_METHOD_NAME, DOCUMENT_DID_SAVE_METHOD_NAME, + NES_ACCEPT_METHOD_NAME, NES_CLOSE_METHOD_NAME, NES_REJECT_METHOD_NAME, NES_START_METHOD_NAME, + NES_SUGGEST_METHOD_NAME, +}; + // Initialize /// Request parameters for the initialize method. @@ -3395,6 +3411,22 @@ pub struct AgentCapabilities { #[cfg(feature = "unstable_logout")] #[serde(default)] pub auth: AgentAuthCapabilities, + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// NES (Next Edit Suggestions) capabilities supported by the agent. + #[cfg(feature = "unstable_nes")] + #[serde(skip_serializing_if = "Option::is_none")] + pub nes: Option, + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// The position encoding selected by the agent from the client's supported encodings. + #[cfg(feature = "unstable_nes")] + #[serde(skip_serializing_if = "Option::is_none")] + pub position_encoding: Option, /// 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. @@ -3450,6 +3482,29 @@ impl AgentCapabilities { self } + /// **UNSTABLE** + /// + /// NES (Next Edit Suggestions) capabilities supported by the agent. + #[cfg(feature = "unstable_nes")] + #[must_use] + pub fn nes(mut self, nes: impl IntoOption) -> Self { + self.nes = nes.into_option(); + self + } + + /// **UNSTABLE** + /// + /// The position encoding selected by the agent from the client's supported encodings. + #[cfg(feature = "unstable_nes")] + #[must_use] + pub fn position_encoding( + mut self, + position_encoding: impl IntoOption, + ) -> Self { + self.position_encoding = position_encoding.into_option(); + self + } + /// 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. @@ -3945,6 +4000,36 @@ pub struct AgentMethodNames { /// Method for logging out of an authenticated session. #[cfg(feature = "unstable_logout")] pub logout: &'static str, + /// Method for starting an NES session. + #[cfg(feature = "unstable_nes")] + pub nes_start: &'static str, + /// Method for requesting a suggestion. + #[cfg(feature = "unstable_nes")] + pub nes_suggest: &'static str, + /// Notification for accepting a suggestion. + #[cfg(feature = "unstable_nes")] + pub nes_accept: &'static str, + /// Notification for rejecting a suggestion. + #[cfg(feature = "unstable_nes")] + pub nes_reject: &'static str, + /// Method for closing an NES session. + #[cfg(feature = "unstable_nes")] + pub nes_close: &'static str, + /// Notification for document open events. + #[cfg(feature = "unstable_nes")] + pub document_did_open: &'static str, + /// Notification for document change events. + #[cfg(feature = "unstable_nes")] + pub document_did_change: &'static str, + /// Notification for document close events. + #[cfg(feature = "unstable_nes")] + pub document_did_close: &'static str, + /// Notification for document save events. + #[cfg(feature = "unstable_nes")] + pub document_did_save: &'static str, + /// Notification for document focus events. + #[cfg(feature = "unstable_nes")] + pub document_did_focus: &'static str, } /// Constant containing all agent method names. @@ -3968,6 +4053,26 @@ pub const AGENT_METHOD_NAMES: AgentMethodNames = AgentMethodNames { session_close: SESSION_CLOSE_METHOD_NAME, #[cfg(feature = "unstable_logout")] logout: LOGOUT_METHOD_NAME, + #[cfg(feature = "unstable_nes")] + nes_start: NES_START_METHOD_NAME, + #[cfg(feature = "unstable_nes")] + nes_suggest: NES_SUGGEST_METHOD_NAME, + #[cfg(feature = "unstable_nes")] + nes_accept: NES_ACCEPT_METHOD_NAME, + #[cfg(feature = "unstable_nes")] + nes_reject: NES_REJECT_METHOD_NAME, + #[cfg(feature = "unstable_nes")] + nes_close: NES_CLOSE_METHOD_NAME, + #[cfg(feature = "unstable_nes")] + document_did_open: DOCUMENT_DID_OPEN_METHOD_NAME, + #[cfg(feature = "unstable_nes")] + document_did_change: DOCUMENT_DID_CHANGE_METHOD_NAME, + #[cfg(feature = "unstable_nes")] + document_did_close: DOCUMENT_DID_CLOSE_METHOD_NAME, + #[cfg(feature = "unstable_nes")] + document_did_save: DOCUMENT_DID_SAVE_METHOD_NAME, + #[cfg(feature = "unstable_nes")] + document_did_focus: DOCUMENT_DID_FOCUS_METHOD_NAME, }; /// Method name for the initialize request. @@ -4149,6 +4254,30 @@ pub enum ClientRequest { /// /// Select a model for a given session. SetSessionModelRequest(SetSessionModelRequest), + #[cfg(feature = "unstable_nes")] + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// Starts an NES session. + StartNesRequest(StartNesRequest), + #[cfg(feature = "unstable_nes")] + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// Requests a code suggestion. + SuggestNesRequest(SuggestNesRequest), + #[cfg(feature = "unstable_nes")] + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// Closes an active NES session and frees up any resources associated with it. + /// + /// The agent must cancel any ongoing work and then free up any resources + /// associated with the NES session. + CloseNesRequest(CloseNesRequest), /// Handles extension method requests from the client. /// /// Extension methods provide a way to add custom functionality while maintaining @@ -4181,6 +4310,12 @@ impl ClientRequest { Self::PromptRequest(_) => AGENT_METHOD_NAMES.session_prompt, #[cfg(feature = "unstable_session_model")] Self::SetSessionModelRequest(_) => AGENT_METHOD_NAMES.session_set_model, + #[cfg(feature = "unstable_nes")] + Self::StartNesRequest(_) => AGENT_METHOD_NAMES.nes_start, + #[cfg(feature = "unstable_nes")] + Self::SuggestNesRequest(_) => AGENT_METHOD_NAMES.nes_suggest, + #[cfg(feature = "unstable_nes")] + Self::CloseNesRequest(_) => AGENT_METHOD_NAMES.nes_close, Self::ExtMethodRequest(ext_request) => &ext_request.method, } } @@ -4216,6 +4351,12 @@ pub enum AgentResponse { PromptResponse(PromptResponse), #[cfg(feature = "unstable_session_model")] SetSessionModelResponse(#[serde(default)] SetSessionModelResponse), + #[cfg(feature = "unstable_nes")] + StartNesResponse(StartNesResponse), + #[cfg(feature = "unstable_nes")] + SuggestNesResponse(SuggestNesResponse), + #[cfg(feature = "unstable_nes")] + CloseNesResponse(#[serde(default)] CloseNesResponse), ExtMethodResponse(ExtResponse), } @@ -4242,6 +4383,41 @@ pub enum ClientNotification { /// /// See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation) CancelNotification(CancelNotification), + #[cfg(feature = "unstable_nes")] + /// **UNSTABLE** + /// + /// Notification sent when a file is opened in the editor. + DidOpenDocumentNotification(DidOpenDocumentNotification), + #[cfg(feature = "unstable_nes")] + /// **UNSTABLE** + /// + /// Notification sent when a file is edited. + DidChangeDocumentNotification(DidChangeDocumentNotification), + #[cfg(feature = "unstable_nes")] + /// **UNSTABLE** + /// + /// Notification sent when a file is closed. + DidCloseDocumentNotification(DidCloseDocumentNotification), + #[cfg(feature = "unstable_nes")] + /// **UNSTABLE** + /// + /// Notification sent when a file is saved. + DidSaveDocumentNotification(DidSaveDocumentNotification), + #[cfg(feature = "unstable_nes")] + /// **UNSTABLE** + /// + /// Notification sent when a file becomes the active editor tab. + DidFocusDocumentNotification(DidFocusDocumentNotification), + #[cfg(feature = "unstable_nes")] + /// **UNSTABLE** + /// + /// Notification sent when a suggestion is accepted. + AcceptNesNotification(AcceptNesNotification), + #[cfg(feature = "unstable_nes")] + /// **UNSTABLE** + /// + /// Notification sent when a suggestion is rejected. + RejectNesNotification(RejectNesNotification), /// Handles extension notifications from the client. /// /// Extension notifications provide a way to send one-way messages for custom functionality @@ -4257,6 +4433,20 @@ impl ClientNotification { pub fn method(&self) -> &str { match self { Self::CancelNotification(_) => AGENT_METHOD_NAMES.session_cancel, + #[cfg(feature = "unstable_nes")] + Self::DidOpenDocumentNotification(_) => AGENT_METHOD_NAMES.document_did_open, + #[cfg(feature = "unstable_nes")] + Self::DidChangeDocumentNotification(_) => AGENT_METHOD_NAMES.document_did_change, + #[cfg(feature = "unstable_nes")] + Self::DidCloseDocumentNotification(_) => AGENT_METHOD_NAMES.document_did_close, + #[cfg(feature = "unstable_nes")] + Self::DidSaveDocumentNotification(_) => AGENT_METHOD_NAMES.document_did_save, + #[cfg(feature = "unstable_nes")] + Self::DidFocusDocumentNotification(_) => AGENT_METHOD_NAMES.document_did_focus, + #[cfg(feature = "unstable_nes")] + Self::AcceptNesNotification(_) => AGENT_METHOD_NAMES.nes_accept, + #[cfg(feature = "unstable_nes")] + Self::RejectNesNotification(_) => AGENT_METHOD_NAMES.nes_reject, Self::ExtNotification(ext_notification) => &ext_notification.method, } } diff --git a/src/bin/generate.rs b/src/bin/generate.rs index 8fd151c8..fd93616b 100644 --- a/src/bin/generate.rs +++ b/src/bin/generate.rs @@ -1033,6 +1033,16 @@ starting with '$/' it is free to ignore the notification." "session/set_model" => self.agent.get("SetSessionModelRequest").unwrap(), "session/close" => self.agent.get("CloseSessionRequest").unwrap(), "logout" => self.agent.get("LogoutRequest").unwrap(), + "nes/start" => self.agent.get("StartNesRequest").unwrap(), + "nes/suggest" => self.agent.get("SuggestNesRequest").unwrap(), + "nes/close" => self.agent.get("CloseNesRequest").unwrap(), + "nes/accept" => self.agent.get("AcceptNesNotification").unwrap(), + "nes/reject" => self.agent.get("RejectNesNotification").unwrap(), + "document/didOpen" => self.agent.get("DidOpenDocumentNotification").unwrap(), + "document/didChange" => self.agent.get("DidChangeDocumentNotification").unwrap(), + "document/didClose" => self.agent.get("DidCloseDocumentNotification").unwrap(), + "document/didSave" => self.agent.get("DidSaveDocumentNotification").unwrap(), + "document/didFocus" => self.agent.get("DidFocusDocumentNotification").unwrap(), _ => panic!("Introduced a method? Add it here :)"), } } diff --git a/src/client.rs b/src/client.rs index ef81f671..0a34cfe3 100644 --- a/src/client.rs +++ b/src/client.rs @@ -20,6 +20,9 @@ use crate::{ }; use crate::{IntoMaybeUndefined, MaybeUndefined}; +#[cfg(feature = "unstable_nes")] +use crate::{ClientNesCapabilities, PositionEncodingKind}; + // Session updates /// Notification containing a session update from the agent. @@ -1500,6 +1503,23 @@ pub struct ClientCapabilities { #[cfg(feature = "unstable_elicitation")] #[serde(default, skip_serializing_if = "Option::is_none")] pub elicitation: Option, + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// NES (Next Edit Suggestions) capabilities supported by the client. + #[cfg(feature = "unstable_nes")] + #[serde(skip_serializing_if = "Option::is_none")] + pub nes: Option, + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// The position encodings supported by the client, in order of preference. + #[cfg(feature = "unstable_nes")] + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub position_encodings: Vec, + /// 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. @@ -1557,6 +1577,26 @@ impl ClientCapabilities { self } + /// **UNSTABLE** + /// + /// NES (Next Edit Suggestions) capabilities supported by the client. + #[cfg(feature = "unstable_nes")] + #[must_use] + pub fn nes(mut self, nes: impl IntoOption) -> Self { + self.nes = nes.into_option(); + self + } + + /// **UNSTABLE** + /// + /// The position encodings supported by the client, in order of preference. + #[cfg(feature = "unstable_nes")] + #[must_use] + pub fn position_encodings(mut self, position_encodings: Vec) -> Self { + self.position_encodings = position_encodings; + self + } + /// 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. @@ -2020,4 +2060,18 @@ mod tests { json!({}) ); } + + #[cfg(feature = "unstable_nes")] + #[test] + fn test_client_capabilities_position_encodings_serialization() { + use serde_json::json; + + let capabilities = ClientCapabilities::new().position_encodings(vec![ + PositionEncodingKind::Utf32, + PositionEncodingKind::Utf16, + ]); + let json = serde_json::to_value(&capabilities).unwrap(); + + assert_eq!(json["positionEncodings"], json!(["utf-32", "utf-16"])); + } } diff --git a/src/lib.rs b/src/lib.rs index f6cdb638..1be0f6c5 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -58,6 +58,8 @@ mod elicitation; mod error; mod ext; mod maybe_undefined; +#[cfg(feature = "unstable_nes")] +mod nes; mod plan; #[cfg(feature = "unstable_cancel_request")] mod protocol_level; @@ -74,6 +76,8 @@ pub use elicitation::*; pub use error::*; pub use ext::*; pub use maybe_undefined::*; +#[cfg(feature = "unstable_nes")] +pub use nes::*; pub use plan::*; #[cfg(feature = "unstable_cancel_request")] pub use protocol_level::*; diff --git a/src/nes.rs b/src/nes.rs new file mode 100644 index 00000000..58323d22 --- /dev/null +++ b/src/nes.rs @@ -0,0 +1,2553 @@ +//! Next Edit Suggestions (NES) types and constants. +//! +//! NES allows agents to provide predictive code edits via capability negotiation, +//! document events, and a suggestion request/response flow. NES sessions are +//! independent of chat sessions and have their own lifecycle. + +use schemars::JsonSchema; +use serde::{Deserialize, Serialize}; + +use crate::{IntoOption, Meta, SessionId}; + +// Method name constants + +/// Method name for starting an NES session. +pub(crate) const NES_START_METHOD_NAME: &str = "nes/start"; +/// Method name for requesting a suggestion. +pub(crate) const NES_SUGGEST_METHOD_NAME: &str = "nes/suggest"; +/// Method name for accepting a suggestion. +pub(crate) const NES_ACCEPT_METHOD_NAME: &str = "nes/accept"; +/// Method name for rejecting a suggestion. +pub(crate) const NES_REJECT_METHOD_NAME: &str = "nes/reject"; +/// Method name for closing an NES session. +pub(crate) const NES_CLOSE_METHOD_NAME: &str = "nes/close"; +/// Notification name for document open events. +pub(crate) const DOCUMENT_DID_OPEN_METHOD_NAME: &str = "document/didOpen"; +/// Notification name for document change events. +pub(crate) const DOCUMENT_DID_CHANGE_METHOD_NAME: &str = "document/didChange"; +/// Notification name for document close events. +pub(crate) const DOCUMENT_DID_CLOSE_METHOD_NAME: &str = "document/didClose"; +/// Notification name for document save events. +pub(crate) const DOCUMENT_DID_SAVE_METHOD_NAME: &str = "document/didSave"; +/// Notification name for document focus events. +pub(crate) const DOCUMENT_DID_FOCUS_METHOD_NAME: &str = "document/didFocus"; + +// Position primitives + +/// The encoding used for character offsets in positions. +/// +/// Follows the same conventions as LSP 3.17. The default is UTF-16. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[non_exhaustive] +pub enum PositionEncodingKind { + /// Character offsets count UTF-16 code units. This is the default. + #[serde(rename = "utf-16")] + Utf16, + /// Character offsets count Unicode code points. + #[serde(rename = "utf-32")] + Utf32, + /// Character offsets count UTF-8 code units (bytes). + #[serde(rename = "utf-8")] + Utf8, +} + +/// A zero-based position in a text document. +/// +/// The meaning of `character` depends on the negotiated position encoding. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct Position { + /// Zero-based line number. + pub line: u32, + /// Zero-based character offset (encoding-dependent). + pub character: u32, +} + +impl Position { + #[must_use] + pub fn new(line: u32, character: u32) -> Self { + Self { line, character } + } +} + +/// A range in a text document, expressed as start and end positions. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct Range { + /// The start position (inclusive). + pub start: Position, + /// The end position (exclusive). + pub end: Position, +} + +impl Range { + #[must_use] + pub fn new(start: Position, end: Position) -> Self { + Self { start, end } + } +} + +// Agent NES capabilities + +/// NES capabilities advertised by the agent during initialization. +#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesCapabilities { + /// Events the agent wants to receive. + #[serde(skip_serializing_if = "Option::is_none")] + pub events: Option, + /// Context the agent wants attached to each suggestion request. + #[serde(skip_serializing_if = "Option::is_none")] + pub context: Option, + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl NesCapabilities { + #[must_use] + pub fn new() -> Self { + Self::default() + } + + #[must_use] + pub fn events(mut self, events: impl IntoOption) -> Self { + self.events = events.into_option(); + self + } + + #[must_use] + pub fn context(mut self, context: impl IntoOption) -> Self { + self.context = context.into_option(); + self + } + + /// 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/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// Event capabilities the agent can consume. +#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesEventCapabilities { + /// Document event capabilities. + #[serde(skip_serializing_if = "Option::is_none")] + pub document: Option, + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl NesEventCapabilities { + #[must_use] + pub fn new() -> Self { + Self::default() + } + + #[must_use] + pub fn document(mut self, document: impl IntoOption) -> Self { + self.document = document.into_option(); + self + } + + /// 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/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// Document event capabilities the agent wants to receive. +#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesDocumentEventCapabilities { + /// Whether the agent wants `document/didOpen` events. + #[serde(skip_serializing_if = "Option::is_none")] + pub did_open: Option, + /// Whether the agent wants `document/didChange` events, and the sync kind. + #[serde(skip_serializing_if = "Option::is_none")] + pub did_change: Option, + /// Whether the agent wants `document/didClose` events. + #[serde(skip_serializing_if = "Option::is_none")] + pub did_close: Option, + /// Whether the agent wants `document/didSave` events. + #[serde(skip_serializing_if = "Option::is_none")] + pub did_save: Option, + /// Whether the agent wants `document/didFocus` events. + #[serde(skip_serializing_if = "Option::is_none")] + pub did_focus: Option, + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl NesDocumentEventCapabilities { + #[must_use] + pub fn new() -> Self { + Self::default() + } + + #[must_use] + pub fn did_open(mut self, did_open: impl IntoOption) -> Self { + self.did_open = did_open.into_option(); + self + } + + #[must_use] + pub fn did_change( + mut self, + did_change: impl IntoOption, + ) -> Self { + self.did_change = did_change.into_option(); + self + } + + #[must_use] + pub fn did_close( + mut self, + did_close: impl IntoOption, + ) -> Self { + self.did_close = did_close.into_option(); + self + } + + #[must_use] + pub fn did_save(mut self, did_save: impl IntoOption) -> Self { + self.did_save = did_save.into_option(); + self + } + + #[must_use] + pub fn did_focus( + mut self, + did_focus: impl IntoOption, + ) -> Self { + self.did_focus = did_focus.into_option(); + self + } + + /// 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/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// Marker for `document/didOpen` capability support. +#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesDocumentDidOpenCapabilities { + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl NesDocumentDidOpenCapabilities { + #[must_use] + pub fn new() -> Self { + Self::default() + } +} + +/// Capabilities for `document/didChange` events. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesDocumentDidChangeCapabilities { + /// The sync kind the agent wants: `"full"` or `"incremental"`. + pub sync_kind: TextDocumentSyncKind, + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl NesDocumentDidChangeCapabilities { + #[must_use] + pub fn new(sync_kind: TextDocumentSyncKind) -> Self { + Self { + sync_kind, + meta: None, + } + } + + /// 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/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// How the agent wants document changes delivered. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[non_exhaustive] +pub enum TextDocumentSyncKind { + /// Client sends the entire file content on each change. + #[serde(rename = "full")] + Full, + /// Client sends only the changed ranges. + #[serde(rename = "incremental")] + Incremental, +} + +/// Marker for `document/didClose` capability support. +#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesDocumentDidCloseCapabilities { + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl NesDocumentDidCloseCapabilities { + #[must_use] + pub fn new() -> Self { + Self::default() + } +} + +/// Marker for `document/didSave` capability support. +#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesDocumentDidSaveCapabilities { + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl NesDocumentDidSaveCapabilities { + #[must_use] + pub fn new() -> Self { + Self::default() + } +} + +/// Marker for `document/didFocus` capability support. +#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesDocumentDidFocusCapabilities { + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl NesDocumentDidFocusCapabilities { + #[must_use] + pub fn new() -> Self { + Self::default() + } +} + +/// Context capabilities the agent wants attached to each suggestion request. +#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesContextCapabilities { + /// Whether the agent wants recent files context. + #[serde(skip_serializing_if = "Option::is_none")] + pub recent_files: Option, + /// Whether the agent wants related snippets context. + #[serde(skip_serializing_if = "Option::is_none")] + pub related_snippets: Option, + /// Whether the agent wants edit history context. + #[serde(skip_serializing_if = "Option::is_none")] + pub edit_history: Option, + /// Whether the agent wants user actions context. + #[serde(skip_serializing_if = "Option::is_none")] + pub user_actions: Option, + /// Whether the agent wants open files context. + #[serde(skip_serializing_if = "Option::is_none")] + pub open_files: Option, + /// Whether the agent wants diagnostics context. + #[serde(skip_serializing_if = "Option::is_none")] + pub diagnostics: Option, + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl NesContextCapabilities { + #[must_use] + pub fn new() -> Self { + Self::default() + } + + #[must_use] + pub fn recent_files( + mut self, + recent_files: impl IntoOption, + ) -> Self { + self.recent_files = recent_files.into_option(); + self + } + + #[must_use] + pub fn related_snippets( + mut self, + related_snippets: impl IntoOption, + ) -> Self { + self.related_snippets = related_snippets.into_option(); + self + } + + #[must_use] + pub fn edit_history( + mut self, + edit_history: impl IntoOption, + ) -> Self { + self.edit_history = edit_history.into_option(); + self + } + + #[must_use] + pub fn user_actions( + mut self, + user_actions: impl IntoOption, + ) -> Self { + self.user_actions = user_actions.into_option(); + self + } + + #[must_use] + pub fn open_files(mut self, open_files: impl IntoOption) -> Self { + self.open_files = open_files.into_option(); + self + } + + #[must_use] + pub fn diagnostics(mut self, diagnostics: impl IntoOption) -> Self { + self.diagnostics = diagnostics.into_option(); + self + } + + /// 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/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// Capabilities for recent files context. +#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesRecentFilesCapabilities { + /// Maximum number of recent files the agent can use. + #[serde(skip_serializing_if = "Option::is_none")] + pub max_count: Option, + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl NesRecentFilesCapabilities { + #[must_use] + pub fn new() -> Self { + Self::default() + } +} + +/// Capabilities for related snippets context. +#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesRelatedSnippetsCapabilities { + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl NesRelatedSnippetsCapabilities { + #[must_use] + pub fn new() -> Self { + Self::default() + } +} + +/// Capabilities for edit history context. +#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesEditHistoryCapabilities { + /// Maximum number of edit history entries the agent can use. + #[serde(skip_serializing_if = "Option::is_none")] + pub max_count: Option, + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl NesEditHistoryCapabilities { + #[must_use] + pub fn new() -> Self { + Self::default() + } +} + +/// Capabilities for user actions context. +#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesUserActionsCapabilities { + /// Maximum number of user actions the agent can use. + #[serde(skip_serializing_if = "Option::is_none")] + pub max_count: Option, + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl NesUserActionsCapabilities { + #[must_use] + pub fn new() -> Self { + Self::default() + } +} + +/// Capabilities for open files context. +#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesOpenFilesCapabilities { + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl NesOpenFilesCapabilities { + #[must_use] + pub fn new() -> Self { + Self::default() + } +} + +/// Capabilities for diagnostics context. +#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesDiagnosticsCapabilities { + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl NesDiagnosticsCapabilities { + #[must_use] + pub fn new() -> Self { + Self::default() + } +} + +// Client NES capabilities + +/// NES capabilities advertised by the client during initialization. +#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct ClientNesCapabilities { + /// Whether the client supports the `jump` suggestion kind. + #[serde(skip_serializing_if = "Option::is_none")] + pub jump: Option, + /// Whether the client supports the `rename` suggestion kind. + #[serde(skip_serializing_if = "Option::is_none")] + pub rename: Option, + /// Whether the client supports the `searchAndReplace` suggestion kind. + #[serde(skip_serializing_if = "Option::is_none")] + pub search_and_replace: Option, + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl ClientNesCapabilities { + #[must_use] + pub fn new() -> Self { + Self::default() + } + + #[must_use] + pub fn jump(mut self, jump: impl IntoOption) -> Self { + self.jump = jump.into_option(); + self + } + + #[must_use] + pub fn rename(mut self, rename: impl IntoOption) -> Self { + self.rename = rename.into_option(); + self + } + + #[must_use] + pub fn search_and_replace( + mut self, + search_and_replace: impl IntoOption, + ) -> Self { + self.search_and_replace = search_and_replace.into_option(); + self + } + + /// 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/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// Marker for jump suggestion support. +#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesJumpCapabilities { + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl NesJumpCapabilities { + #[must_use] + pub fn new() -> Self { + Self::default() + } +} + +/// Marker for rename suggestion support. +#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesRenameCapabilities { + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl NesRenameCapabilities { + #[must_use] + pub fn new() -> Self { + Self::default() + } +} + +/// Marker for search and replace suggestion support. +#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesSearchAndReplaceCapabilities { + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl NesSearchAndReplaceCapabilities { + #[must_use] + pub fn new() -> Self { + Self::default() + } +} + +// Document event notifications (client -> agent) + +/// Notification sent when a file is opened in the editor. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[schemars(extend("x-side" = "agent", "x-method" = DOCUMENT_DID_OPEN_METHOD_NAME))] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct DidOpenDocumentNotification { + /// The session ID for this notification. + pub session_id: SessionId, + /// The URI of the opened document. + pub uri: String, + /// The language identifier of the document (e.g., "rust", "python"). + pub language_id: String, + /// The version number of the document. + pub version: i64, + /// The full text content of the document. + pub text: String, + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl DidOpenDocumentNotification { + #[must_use] + pub fn new( + session_id: impl Into, + uri: impl Into, + language_id: impl Into, + version: i64, + text: impl Into, + ) -> Self { + Self { + session_id: session_id.into(), + uri: uri.into(), + language_id: language_id.into(), + version, + text: text.into(), + meta: None, + } + } + + /// 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/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// Notification sent when a file is edited. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[schemars(extend("x-side" = "agent", "x-method" = DOCUMENT_DID_CHANGE_METHOD_NAME))] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct DidChangeDocumentNotification { + /// The session ID for this notification. + pub session_id: SessionId, + /// The URI of the changed document. + pub uri: String, + /// The new version number of the document. + pub version: i64, + /// The content changes. + pub content_changes: Vec, + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl DidChangeDocumentNotification { + #[must_use] + pub fn new( + session_id: impl Into, + uri: impl Into, + version: i64, + content_changes: Vec, + ) -> Self { + Self { + session_id: session_id.into(), + uri: uri.into(), + version, + content_changes, + meta: None, + } + } + + /// 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/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// A content change event for a document. +/// +/// When `range` is `None`, `text` is the full content of the document. +/// When `range` is `Some`, `text` replaces the given range. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct TextDocumentContentChangeEvent { + /// The range of the document that changed. If `None`, the entire content is replaced. + #[serde(skip_serializing_if = "Option::is_none")] + pub range: Option, + /// The new text for the range, or the full document content if `range` is `None`. + pub text: String, +} + +impl TextDocumentContentChangeEvent { + #[must_use] + pub fn full(text: impl Into) -> Self { + Self { + range: None, + text: text.into(), + } + } + + #[must_use] + pub fn incremental(range: Range, text: impl Into) -> Self { + Self { + range: Some(range), + text: text.into(), + } + } +} + +/// Notification sent when a file is closed. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[schemars(extend("x-side" = "agent", "x-method" = DOCUMENT_DID_CLOSE_METHOD_NAME))] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct DidCloseDocumentNotification { + /// The session ID for this notification. + pub session_id: SessionId, + /// The URI of the closed document. + pub uri: String, + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl DidCloseDocumentNotification { + #[must_use] + pub fn new(session_id: impl Into, uri: impl Into) -> Self { + Self { + session_id: session_id.into(), + uri: uri.into(), + meta: None, + } + } + + /// 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/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// Notification sent when a file is saved. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[schemars(extend("x-side" = "agent", "x-method" = DOCUMENT_DID_SAVE_METHOD_NAME))] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct DidSaveDocumentNotification { + /// The session ID for this notification. + pub session_id: SessionId, + /// The URI of the saved document. + pub uri: String, + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl DidSaveDocumentNotification { + #[must_use] + pub fn new(session_id: impl Into, uri: impl Into) -> Self { + Self { + session_id: session_id.into(), + uri: uri.into(), + meta: None, + } + } + + /// 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/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// Notification sent when a file becomes the active editor tab. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[schemars(extend("x-side" = "agent", "x-method" = DOCUMENT_DID_FOCUS_METHOD_NAME))] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct DidFocusDocumentNotification { + /// The session ID for this notification. + pub session_id: SessionId, + /// The URI of the focused document. + pub uri: String, + /// The version number of the document. + pub version: i64, + /// The current cursor position. + pub position: Position, + /// The portion of the file currently visible in the editor viewport. + pub visible_range: Range, + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl DidFocusDocumentNotification { + #[must_use] + pub fn new( + session_id: impl Into, + uri: impl Into, + version: i64, + position: Position, + visible_range: Range, + ) -> Self { + Self { + session_id: session_id.into(), + uri: uri.into(), + version, + position, + visible_range, + meta: None, + } + } + + /// 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/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +// NES session start + +/// Request to start an NES session. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[schemars(extend("x-side" = "agent", "x-method" = NES_START_METHOD_NAME))] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct StartNesRequest { + /// The root URI of the workspace. + #[serde(skip_serializing_if = "Option::is_none")] + pub workspace_uri: Option, + /// The workspace folders. + #[serde(skip_serializing_if = "Option::is_none")] + pub workspace_folders: Option>, + /// Repository metadata, if the workspace is a git repository. + #[serde(skip_serializing_if = "Option::is_none")] + pub repository: Option, + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl StartNesRequest { + #[must_use] + pub fn new() -> Self { + Self { + workspace_uri: None, + workspace_folders: None, + repository: None, + meta: None, + } + } + + #[must_use] + pub fn workspace_uri(mut self, workspace_uri: impl IntoOption) -> Self { + self.workspace_uri = workspace_uri.into_option(); + self + } + + #[must_use] + pub fn workspace_folders( + mut self, + workspace_folders: impl IntoOption>, + ) -> Self { + self.workspace_folders = workspace_folders.into_option(); + self + } + + #[must_use] + pub fn repository(mut self, repository: impl IntoOption) -> Self { + self.repository = repository.into_option(); + self + } + + /// 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/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +impl Default for StartNesRequest { + fn default() -> Self { + Self::new() + } +} + +/// A workspace folder. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct WorkspaceFolder { + /// The URI of the folder. + pub uri: String, + /// The display name of the folder. + pub name: String, +} + +impl WorkspaceFolder { + #[must_use] + pub fn new(uri: impl Into, name: impl Into) -> Self { + Self { + uri: uri.into(), + name: name.into(), + } + } +} + +/// Repository metadata for an NES session. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesRepository { + /// The repository name. + pub name: String, + /// The repository owner. + pub owner: String, + /// The remote URL of the repository. + pub remote_url: String, +} + +impl NesRepository { + #[must_use] + pub fn new( + name: impl Into, + owner: impl Into, + remote_url: impl Into, + ) -> Self { + Self { + name: name.into(), + owner: owner.into(), + remote_url: remote_url.into(), + } + } +} + +/// Response to `nes/start`. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[schemars(extend("x-side" = "agent", "x-method" = NES_START_METHOD_NAME))] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct StartNesResponse { + /// The session ID for the newly started NES session. + pub session_id: SessionId, + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl StartNesResponse { + #[must_use] + pub fn new(session_id: impl Into) -> Self { + Self { + session_id: session_id.into(), + meta: None, + } + } + + /// 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/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +// NES session close + +/// Request to close an NES session. +/// +/// The agent **must** cancel any ongoing work related to the NES session +/// and then free up any resources associated with the session. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[schemars(extend("x-side" = "agent", "x-method" = NES_CLOSE_METHOD_NAME))] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct CloseNesRequest { + /// The ID of the NES session to close. + pub session_id: SessionId, + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl CloseNesRequest { + #[must_use] + pub fn new(session_id: impl Into) -> Self { + Self { + session_id: session_id.into(), + meta: None, + } + } + + /// 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/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// Response from closing an NES session. +#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[schemars(extend("x-side" = "agent", "x-method" = NES_CLOSE_METHOD_NAME))] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct CloseNesResponse { + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl CloseNesResponse { + #[must_use] + pub fn new() -> Self { + Self::default() + } + + /// 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/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +// NES suggest request + +/// What triggered the suggestion request. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[non_exhaustive] +pub enum NesTriggerKind { + /// Triggered by user typing or cursor movement. + #[serde(rename = "automatic")] + Automatic, + /// Triggered by a diagnostic appearing at or near the cursor. + #[serde(rename = "diagnostic")] + Diagnostic, + /// Triggered by an explicit user action (keyboard shortcut). + #[serde(rename = "manual")] + Manual, +} + +/// Request for a code suggestion. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[schemars(extend("x-side" = "agent", "x-method" = NES_SUGGEST_METHOD_NAME))] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct SuggestNesRequest { + /// The session ID for this request. + pub session_id: SessionId, + /// The URI of the document to suggest for. + pub uri: String, + /// The version number of the document. + pub version: i64, + /// The current cursor position. + pub position: Position, + /// The current text selection range, if any. + #[serde(skip_serializing_if = "Option::is_none")] + pub selection: Option, + /// What triggered this suggestion request. + pub trigger_kind: NesTriggerKind, + /// Context for the suggestion, included based on agent capabilities. + #[serde(skip_serializing_if = "Option::is_none")] + pub context: Option, + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl SuggestNesRequest { + #[must_use] + pub fn new( + session_id: impl Into, + uri: impl Into, + version: i64, + position: Position, + trigger_kind: NesTriggerKind, + ) -> Self { + Self { + session_id: session_id.into(), + uri: uri.into(), + version, + position, + selection: None, + trigger_kind, + context: None, + meta: None, + } + } + + #[must_use] + pub fn selection(mut self, selection: impl IntoOption) -> Self { + self.selection = selection.into_option(); + self + } + + #[must_use] + pub fn context(mut self, context: impl IntoOption) -> Self { + self.context = context.into_option(); + self + } + + /// 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/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// Context attached to a suggestion request. +#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesSuggestContext { + /// Recently accessed files. + #[serde(skip_serializing_if = "Option::is_none")] + pub recent_files: Option>, + /// Related code snippets. + #[serde(skip_serializing_if = "Option::is_none")] + pub related_snippets: Option>, + /// Recent edit history. + #[serde(skip_serializing_if = "Option::is_none")] + pub edit_history: Option>, + /// Recent user actions (typing, navigation, etc.). + #[serde(skip_serializing_if = "Option::is_none")] + pub user_actions: Option>, + /// Currently open files in the editor. + #[serde(skip_serializing_if = "Option::is_none")] + pub open_files: Option>, + /// Current diagnostics (errors, warnings). + #[serde(skip_serializing_if = "Option::is_none")] + pub diagnostics: Option>, + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl NesSuggestContext { + #[must_use] + pub fn new() -> Self { + Self::default() + } + + #[must_use] + pub fn recent_files(mut self, recent_files: impl IntoOption>) -> Self { + self.recent_files = recent_files.into_option(); + self + } + + #[must_use] + pub fn related_snippets( + mut self, + related_snippets: impl IntoOption>, + ) -> Self { + self.related_snippets = related_snippets.into_option(); + self + } + + #[must_use] + pub fn edit_history(mut self, edit_history: impl IntoOption>) -> Self { + self.edit_history = edit_history.into_option(); + self + } + + #[must_use] + pub fn user_actions(mut self, user_actions: impl IntoOption>) -> Self { + self.user_actions = user_actions.into_option(); + self + } + + #[must_use] + pub fn open_files(mut self, open_files: impl IntoOption>) -> Self { + self.open_files = open_files.into_option(); + self + } + + #[must_use] + pub fn diagnostics(mut self, diagnostics: impl IntoOption>) -> Self { + self.diagnostics = diagnostics.into_option(); + self + } + + /// 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/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// A recently accessed file. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesRecentFile { + /// The URI of the file. + pub uri: String, + /// The language identifier. + pub language_id: String, + /// The full text content of the file. + pub text: String, +} + +impl NesRecentFile { + #[must_use] + pub fn new( + uri: impl Into, + language_id: impl Into, + text: impl Into, + ) -> Self { + Self { + uri: uri.into(), + language_id: language_id.into(), + text: text.into(), + } + } +} + +/// A related code snippet from a file. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesRelatedSnippet { + /// The URI of the file containing the snippets. + pub uri: String, + /// The code excerpts. + pub excerpts: Vec, +} + +impl NesRelatedSnippet { + #[must_use] + pub fn new(uri: impl Into, excerpts: Vec) -> Self { + Self { + uri: uri.into(), + excerpts, + } + } +} + +/// A code excerpt from a file. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesExcerpt { + /// The start line of the excerpt (zero-based). + pub start_line: u32, + /// The end line of the excerpt (zero-based). + pub end_line: u32, + /// The text content of the excerpt. + pub text: String, +} + +impl NesExcerpt { + #[must_use] + pub fn new(start_line: u32, end_line: u32, text: impl Into) -> Self { + Self { + start_line, + end_line, + text: text.into(), + } + } +} + +/// An entry in the edit history. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesEditHistoryEntry { + /// The URI of the edited file. + pub uri: String, + /// A diff representing the edit. + pub diff: String, +} + +impl NesEditHistoryEntry { + #[must_use] + pub fn new(uri: impl Into, diff: impl Into) -> Self { + Self { + uri: uri.into(), + diff: diff.into(), + } + } +} + +/// A user action (typing, cursor movement, etc.). +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesUserAction { + /// The kind of action (e.g., "insertChar", "cursorMovement"). + pub action: String, + /// The URI of the file where the action occurred. + pub uri: String, + /// The position where the action occurred. + pub position: Position, + /// Timestamp in milliseconds since epoch. + pub timestamp_ms: u64, +} + +impl NesUserAction { + #[must_use] + pub fn new( + action: impl Into, + uri: impl Into, + position: Position, + timestamp_ms: u64, + ) -> Self { + Self { + action: action.into(), + uri: uri.into(), + position, + timestamp_ms, + } + } +} + +/// An open file in the editor. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesOpenFile { + /// The URI of the file. + pub uri: String, + /// The language identifier. + pub language_id: String, + /// The visible range in the editor, if any. + #[serde(skip_serializing_if = "Option::is_none")] + pub visible_range: Option, + /// Timestamp in milliseconds since epoch of when the file was last focused. + #[serde(skip_serializing_if = "Option::is_none")] + pub last_focused_ms: Option, +} + +impl NesOpenFile { + #[must_use] + pub fn new(uri: impl Into, language_id: impl Into) -> Self { + Self { + uri: uri.into(), + language_id: language_id.into(), + visible_range: None, + last_focused_ms: None, + } + } + + #[must_use] + pub fn visible_range(mut self, visible_range: impl IntoOption) -> Self { + self.visible_range = visible_range.into_option(); + self + } + + #[must_use] + pub fn last_focused_ms(mut self, last_focused_ms: impl IntoOption) -> Self { + self.last_focused_ms = last_focused_ms.into_option(); + self + } +} + +/// A diagnostic (error, warning, etc.). +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesDiagnostic { + /// The URI of the file containing the diagnostic. + pub uri: String, + /// The range of the diagnostic. + pub range: Range, + /// The severity of the diagnostic. + pub severity: NesDiagnosticSeverity, + /// The diagnostic message. + pub message: String, +} + +impl NesDiagnostic { + #[must_use] + pub fn new( + uri: impl Into, + range: Range, + severity: NesDiagnosticSeverity, + message: impl Into, + ) -> Self { + Self { + uri: uri.into(), + range, + severity, + message: message.into(), + } + } +} + +/// Severity of a diagnostic. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[non_exhaustive] +pub enum NesDiagnosticSeverity { + /// An error. + #[serde(rename = "error")] + Error, + /// A warning. + #[serde(rename = "warning")] + Warning, + /// An informational message. + #[serde(rename = "information")] + Information, + /// A hint. + #[serde(rename = "hint")] + Hint, +} + +// NES suggest response + +/// Response to `nes/suggest`. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[schemars(extend("x-side" = "agent", "x-method" = NES_SUGGEST_METHOD_NAME))] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct SuggestNesResponse { + /// The list of suggestions. + pub suggestions: Vec, + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl SuggestNesResponse { + #[must_use] + pub fn new(suggestions: Vec) -> Self { + Self { + suggestions, + meta: None, + } + } + + /// 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/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// A suggestion returned by the agent. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(tag = "kind", rename_all = "camelCase")] +#[schemars(extend("discriminator" = {"propertyName": "kind"}))] +#[non_exhaustive] +pub enum NesSuggestion { + /// A text edit suggestion. + Edit(NesEditSuggestion), + /// A jump-to-location suggestion. + Jump(NesJumpSuggestion), + /// A rename symbol suggestion. + Rename(NesRenameSuggestion), + /// A search-and-replace suggestion. + SearchAndReplace(NesSearchAndReplaceSuggestion), +} + +/// A text edit suggestion. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesEditSuggestion { + /// Unique identifier for accept/reject tracking. + pub id: String, + /// The URI of the file to edit. + pub uri: String, + /// The text edits to apply. + pub edits: Vec, + /// Optional suggested cursor position after applying edits. + #[serde(skip_serializing_if = "Option::is_none")] + pub cursor_position: Option, +} + +impl NesEditSuggestion { + #[must_use] + pub fn new(id: impl Into, uri: impl Into, edits: Vec) -> Self { + Self { + id: id.into(), + uri: uri.into(), + edits, + cursor_position: None, + } + } + + #[must_use] + pub fn cursor_position(mut self, cursor_position: impl IntoOption) -> Self { + self.cursor_position = cursor_position.into_option(); + self + } +} + +/// A text edit within a suggestion. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesTextEdit { + /// The range to replace. + pub range: Range, + /// The replacement text. + pub new_text: String, +} + +impl NesTextEdit { + #[must_use] + pub fn new(range: Range, new_text: impl Into) -> Self { + Self { + range, + new_text: new_text.into(), + } + } +} + +/// A jump-to-location suggestion. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesJumpSuggestion { + /// Unique identifier for accept/reject tracking. + pub id: String, + /// The file to navigate to. + pub uri: String, + /// The target position within the file. + pub position: Position, +} + +impl NesJumpSuggestion { + #[must_use] + pub fn new(id: impl Into, uri: impl Into, position: Position) -> Self { + Self { + id: id.into(), + uri: uri.into(), + position, + } + } +} + +/// A rename symbol suggestion. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesRenameSuggestion { + /// Unique identifier for accept/reject tracking. + pub id: String, + /// The file URI containing the symbol. + pub uri: String, + /// The position of the symbol to rename. + pub position: Position, + /// The new name for the symbol. + pub new_name: String, +} + +impl NesRenameSuggestion { + #[must_use] + pub fn new( + id: impl Into, + uri: impl Into, + position: Position, + new_name: impl Into, + ) -> Self { + Self { + id: id.into(), + uri: uri.into(), + position, + new_name: new_name.into(), + } + } +} + +/// A search-and-replace suggestion. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct NesSearchAndReplaceSuggestion { + /// Unique identifier for accept/reject tracking. + pub id: String, + /// The file URI to search within. + pub uri: String, + /// The text or pattern to find. + pub search: String, + /// The replacement text. + pub replace: String, + /// Whether `search` is a regular expression. Defaults to `false`. + #[serde(skip_serializing_if = "Option::is_none")] + pub is_regex: Option, +} + +impl NesSearchAndReplaceSuggestion { + #[must_use] + pub fn new( + id: impl Into, + uri: impl Into, + search: impl Into, + replace: impl Into, + ) -> Self { + Self { + id: id.into(), + uri: uri.into(), + search: search.into(), + replace: replace.into(), + is_regex: None, + } + } + + #[must_use] + pub fn is_regex(mut self, is_regex: impl IntoOption) -> Self { + self.is_regex = is_regex.into_option(); + self + } +} + +// NES accept/reject notifications + +/// Notification sent when a suggestion is accepted. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[schemars(extend("x-side" = "agent", "x-method" = NES_ACCEPT_METHOD_NAME))] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct AcceptNesNotification { + /// The session ID for this notification. + pub session_id: SessionId, + /// The ID of the accepted suggestion. + pub id: String, + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl AcceptNesNotification { + #[must_use] + pub fn new(session_id: impl Into, id: impl Into) -> Self { + Self { + session_id: session_id.into(), + id: id.into(), + meta: None, + } + } + + /// 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/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// Notification sent when a suggestion is rejected. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[schemars(extend("x-side" = "agent", "x-method" = NES_REJECT_METHOD_NAME))] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct RejectNesNotification { + /// The session ID for this notification. + pub session_id: SessionId, + /// The ID of the rejected suggestion. + pub id: String, + /// The reason for rejection. + #[serde(skip_serializing_if = "Option::is_none")] + pub reason: Option, + /// 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/extensibility) + #[serde(skip_serializing_if = "Option::is_none", rename = "_meta")] + pub meta: Option, +} + +impl RejectNesNotification { + #[must_use] + pub fn new(session_id: impl Into, id: impl Into) -> Self { + Self { + session_id: session_id.into(), + id: id.into(), + reason: None, + meta: None, + } + } + + #[must_use] + pub fn reason(mut self, reason: impl IntoOption) -> Self { + self.reason = reason.into_option(); + self + } + + /// 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/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// The reason a suggestion was rejected. +#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] +#[non_exhaustive] +pub enum NesRejectReason { + /// The user explicitly dismissed the suggestion. + #[serde(rename = "rejected")] + Rejected, + /// The suggestion was shown but the user continued editing without interacting. + #[serde(rename = "ignored")] + Ignored, + /// The suggestion was superseded by a newer suggestion. + #[serde(rename = "replaced")] + Replaced, + /// The request was cancelled before the agent returned a response. + #[serde(rename = "cancelled")] + Cancelled, +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + + #[test] + fn test_position_encoding_kind_serialization() { + assert_eq!( + serde_json::to_value(&PositionEncodingKind::Utf16).unwrap(), + json!("utf-16") + ); + assert_eq!( + serde_json::to_value(&PositionEncodingKind::Utf32).unwrap(), + json!("utf-32") + ); + assert_eq!( + serde_json::to_value(&PositionEncodingKind::Utf8).unwrap(), + json!("utf-8") + ); + + assert_eq!( + serde_json::from_value::(json!("utf-16")).unwrap(), + PositionEncodingKind::Utf16 + ); + assert_eq!( + serde_json::from_value::(json!("utf-32")).unwrap(), + PositionEncodingKind::Utf32 + ); + assert_eq!( + serde_json::from_value::(json!("utf-8")).unwrap(), + PositionEncodingKind::Utf8 + ); + } + + #[test] + fn test_agent_nes_capabilities_serialization() { + let caps = NesCapabilities::new() + .events( + NesEventCapabilities::new().document( + NesDocumentEventCapabilities::new() + .did_open(NesDocumentDidOpenCapabilities::default()) + .did_change(NesDocumentDidChangeCapabilities::new( + TextDocumentSyncKind::Incremental, + )) + .did_close(NesDocumentDidCloseCapabilities::default()) + .did_save(NesDocumentDidSaveCapabilities::default()) + .did_focus(NesDocumentDidFocusCapabilities::default()), + ), + ) + .context( + NesContextCapabilities::new() + .recent_files(NesRecentFilesCapabilities { + max_count: Some(10), + meta: None, + }) + .related_snippets(NesRelatedSnippetsCapabilities::default()) + .edit_history(NesEditHistoryCapabilities { + max_count: Some(6), + meta: None, + }) + .user_actions(NesUserActionsCapabilities { + max_count: Some(16), + meta: None, + }) + .open_files(NesOpenFilesCapabilities::default()) + .diagnostics(NesDiagnosticsCapabilities::default()), + ); + + let json = serde_json::to_value(&caps).unwrap(); + assert_eq!( + json, + json!({ + "events": { + "document": { + "didOpen": {}, + "didChange": { + "syncKind": "incremental" + }, + "didClose": {}, + "didSave": {}, + "didFocus": {} + } + }, + "context": { + "recentFiles": { + "maxCount": 10 + }, + "relatedSnippets": {}, + "editHistory": { + "maxCount": 6 + }, + "userActions": { + "maxCount": 16 + }, + "openFiles": {}, + "diagnostics": {} + } + }) + ); + + // Round-trip + let deserialized: NesCapabilities = serde_json::from_value(json).unwrap(); + assert_eq!(deserialized, caps); + } + + #[test] + fn test_client_nes_capabilities_serialization() { + let caps = ClientNesCapabilities::new() + .jump(NesJumpCapabilities::default()) + .rename(NesRenameCapabilities::default()) + .search_and_replace(NesSearchAndReplaceCapabilities::default()); + + let json = serde_json::to_value(&caps).unwrap(); + assert_eq!( + json, + json!({ + "jump": {}, + "rename": {}, + "searchAndReplace": {} + }) + ); + + let deserialized: ClientNesCapabilities = serde_json::from_value(json).unwrap(); + assert_eq!(deserialized, caps); + } + + #[test] + fn test_document_did_open_serialization() { + let notification = DidOpenDocumentNotification::new( + "session_123", + "file:///path/to/file.rs", + "rust", + 1, + "fn main() {\n println!(\"hello\");\n}\n", + ); + + let json = serde_json::to_value(¬ification).unwrap(); + assert_eq!( + json, + json!({ + "sessionId": "session_123", + "uri": "file:///path/to/file.rs", + "languageId": "rust", + "version": 1, + "text": "fn main() {\n println!(\"hello\");\n}\n" + }) + ); + + let deserialized: DidOpenDocumentNotification = serde_json::from_value(json).unwrap(); + assert_eq!(deserialized, notification); + } + + #[test] + fn test_document_did_change_incremental_serialization() { + let notification = DidChangeDocumentNotification::new( + "session_123", + "file:///path/to/file.rs", + 2, + vec![TextDocumentContentChangeEvent::incremental( + Range::new(Position::new(1, 4), Position::new(1, 4)), + "let x = 42;\n ", + )], + ); + + let json = serde_json::to_value(¬ification).unwrap(); + assert_eq!( + json, + json!({ + "sessionId": "session_123", + "uri": "file:///path/to/file.rs", + "version": 2, + "contentChanges": [ + { + "range": { + "start": { "line": 1, "character": 4 }, + "end": { "line": 1, "character": 4 } + }, + "text": "let x = 42;\n " + } + ] + }) + ); + } + + #[test] + fn test_document_did_change_full_serialization() { + let notification = DidChangeDocumentNotification::new( + "session_123", + "file:///path/to/file.rs", + 2, + vec![TextDocumentContentChangeEvent::full( + "fn main() {\n let x = 42;\n println!(\"hello\");\n}\n", + )], + ); + + let json = serde_json::to_value(¬ification).unwrap(); + assert_eq!( + json, + json!({ + "sessionId": "session_123", + "uri": "file:///path/to/file.rs", + "version": 2, + "contentChanges": [ + { + "text": "fn main() {\n let x = 42;\n println!(\"hello\");\n}\n" + } + ] + }) + ); + } + + #[test] + fn test_document_did_close_serialization() { + let notification = + DidCloseDocumentNotification::new("session_123", "file:///path/to/file.rs"); + let json = serde_json::to_value(¬ification).unwrap(); + assert_eq!( + json, + json!({ "sessionId": "session_123", "uri": "file:///path/to/file.rs" }) + ); + } + + #[test] + fn test_document_did_save_serialization() { + let notification = + DidSaveDocumentNotification::new("session_123", "file:///path/to/file.rs"); + let json = serde_json::to_value(¬ification).unwrap(); + assert_eq!( + json, + json!({ "sessionId": "session_123", "uri": "file:///path/to/file.rs" }) + ); + } + + #[test] + fn test_document_did_focus_serialization() { + let notification = DidFocusDocumentNotification::new( + "session_123", + "file:///path/to/file.rs", + 2, + Position::new(5, 12), + Range::new(Position::new(0, 0), Position::new(45, 0)), + ); + + let json = serde_json::to_value(¬ification).unwrap(); + assert_eq!( + json, + json!({ + "sessionId": "session_123", + "uri": "file:///path/to/file.rs", + "version": 2, + "position": { "line": 5, "character": 12 }, + "visibleRange": { + "start": { "line": 0, "character": 0 }, + "end": { "line": 45, "character": 0 } + } + }) + ); + } + + #[test] + fn test_nes_suggestion_edit_serialization() { + let suggestion = NesSuggestion::Edit( + NesEditSuggestion::new( + "sugg_001", + "file:///path/to/other_file.rs", + vec![NesTextEdit::new( + Range::new(Position::new(5, 0), Position::new(5, 10)), + "let result = helper();", + )], + ) + .cursor_position(Position::new(5, 22)), + ); + + let json = serde_json::to_value(&suggestion).unwrap(); + assert_eq!( + json, + json!({ + "kind": "edit", + "id": "sugg_001", + "uri": "file:///path/to/other_file.rs", + "edits": [ + { + "range": { + "start": { "line": 5, "character": 0 }, + "end": { "line": 5, "character": 10 } + }, + "newText": "let result = helper();" + } + ], + "cursorPosition": { "line": 5, "character": 22 } + }) + ); + + let deserialized: NesSuggestion = serde_json::from_value(json).unwrap(); + assert_eq!(deserialized, suggestion); + } + + #[test] + fn test_nes_suggestion_jump_serialization() { + let suggestion = NesSuggestion::Jump(NesJumpSuggestion::new( + "sugg_002", + "file:///path/to/other_file.rs", + Position::new(15, 4), + )); + + let json = serde_json::to_value(&suggestion).unwrap(); + assert_eq!( + json, + json!({ + "kind": "jump", + "id": "sugg_002", + "uri": "file:///path/to/other_file.rs", + "position": { "line": 15, "character": 4 } + }) + ); + + let deserialized: NesSuggestion = serde_json::from_value(json).unwrap(); + assert_eq!(deserialized, suggestion); + } + + #[test] + fn test_nes_suggestion_rename_serialization() { + let suggestion = NesSuggestion::Rename(NesRenameSuggestion::new( + "sugg_003", + "file:///path/to/file.rs", + Position::new(5, 10), + "calculateTotal", + )); + + let json = serde_json::to_value(&suggestion).unwrap(); + assert_eq!( + json, + json!({ + "kind": "rename", + "id": "sugg_003", + "uri": "file:///path/to/file.rs", + "position": { "line": 5, "character": 10 }, + "newName": "calculateTotal" + }) + ); + + let deserialized: NesSuggestion = serde_json::from_value(json).unwrap(); + assert_eq!(deserialized, suggestion); + } + + #[test] + fn test_nes_suggestion_search_and_replace_serialization() { + let suggestion = NesSuggestion::SearchAndReplace( + NesSearchAndReplaceSuggestion::new( + "sugg_004", + "file:///path/to/file.rs", + "oldFunction", + "newFunction", + ) + .is_regex(false), + ); + + let json = serde_json::to_value(&suggestion).unwrap(); + assert_eq!( + json, + json!({ + "kind": "searchAndReplace", + "id": "sugg_004", + "uri": "file:///path/to/file.rs", + "search": "oldFunction", + "replace": "newFunction", + "isRegex": false + }) + ); + + let deserialized: NesSuggestion = serde_json::from_value(json).unwrap(); + assert_eq!(deserialized, suggestion); + } + + #[test] + fn test_nes_start_request_serialization() { + let request = StartNesRequest::new() + .workspace_uri("file:///Users/alice/projects/my-app") + .workspace_folders(vec![WorkspaceFolder::new( + "file:///Users/alice/projects/my-app", + "my-app", + )]) + .repository(NesRepository::new( + "my-app", + "alice", + "https://github.com/alice/my-app.git", + )); + + let json = serde_json::to_value(&request).unwrap(); + assert_eq!( + json, + json!({ + "workspaceUri": "file:///Users/alice/projects/my-app", + "workspaceFolders": [ + { + "uri": "file:///Users/alice/projects/my-app", + "name": "my-app" + } + ], + "repository": { + "name": "my-app", + "owner": "alice", + "remoteUrl": "https://github.com/alice/my-app.git" + } + }) + ); + } + + #[test] + fn test_nes_start_response_serialization() { + let response = StartNesResponse::new("session_abc123"); + let json = serde_json::to_value(&response).unwrap(); + assert_eq!(json, json!({ "sessionId": "session_abc123" })); + } + + #[test] + fn test_nes_trigger_kind_serialization() { + assert_eq!( + serde_json::to_value(&NesTriggerKind::Automatic).unwrap(), + json!("automatic") + ); + assert_eq!( + serde_json::to_value(&NesTriggerKind::Diagnostic).unwrap(), + json!("diagnostic") + ); + assert_eq!( + serde_json::to_value(&NesTriggerKind::Manual).unwrap(), + json!("manual") + ); + } + + #[test] + fn test_nes_reject_reason_serialization() { + assert_eq!( + serde_json::to_value(&NesRejectReason::Rejected).unwrap(), + json!("rejected") + ); + assert_eq!( + serde_json::to_value(&NesRejectReason::Ignored).unwrap(), + json!("ignored") + ); + assert_eq!( + serde_json::to_value(&NesRejectReason::Replaced).unwrap(), + json!("replaced") + ); + assert_eq!( + serde_json::to_value(&NesRejectReason::Cancelled).unwrap(), + json!("cancelled") + ); + } + + #[test] + fn test_nes_accept_notification_serialization() { + let notification = AcceptNesNotification::new("session_123", "sugg_001"); + let json = serde_json::to_value(¬ification).unwrap(); + assert_eq!( + json, + json!({ "sessionId": "session_123", "id": "sugg_001" }) + ); + } + + #[test] + fn test_nes_reject_notification_serialization() { + let notification = + RejectNesNotification::new("session_123", "sugg_001").reason(NesRejectReason::Rejected); + let json = serde_json::to_value(¬ification).unwrap(); + assert_eq!( + json, + json!({ "sessionId": "session_123", "id": "sugg_001", "reason": "rejected" }) + ); + } + + #[test] + fn test_nes_suggest_request_with_context_serialization() { + let request = SuggestNesRequest::new( + "session_123", + "file:///path/to/file.rs", + 2, + Position::new(5, 12), + NesTriggerKind::Automatic, + ) + .selection(Range::new(Position::new(5, 4), Position::new(5, 12))) + .context( + NesSuggestContext::new() + .recent_files(vec![NesRecentFile::new( + "file:///path/to/utils.rs", + "rust", + "pub fn helper() -> i32 { 42 }\n", + )]) + .diagnostics(vec![NesDiagnostic::new( + "file:///path/to/file.rs", + Range::new(Position::new(5, 0), Position::new(5, 10)), + NesDiagnosticSeverity::Error, + "cannot find value `foo` in this scope", + )]), + ); + + let json = serde_json::to_value(&request).unwrap(); + assert_eq!(json["sessionId"], "session_123"); + assert_eq!(json["uri"], "file:///path/to/file.rs"); + assert_eq!(json["version"], 2); + assert_eq!(json["triggerKind"], "automatic"); + assert_eq!( + json["context"]["recentFiles"][0]["uri"], + "file:///path/to/utils.rs" + ); + assert_eq!(json["context"]["diagnostics"][0]["severity"], "error"); + } + + #[test] + fn test_text_document_sync_kind_serialization() { + assert_eq!( + serde_json::to_value(&TextDocumentSyncKind::Full).unwrap(), + json!("full") + ); + assert_eq!( + serde_json::to_value(&TextDocumentSyncKind::Incremental).unwrap(), + json!("incremental") + ); + } + + #[test] + fn test_document_did_change_capabilities_requires_sync_kind() { + assert!(serde_json::from_value::(json!({})).is_err()); + } + + #[test] + fn test_nes_suggest_response_serialization() { + let response = SuggestNesResponse::new(vec![ + NesSuggestion::Edit(NesEditSuggestion::new( + "sugg_001", + "file:///path/to/file.rs", + vec![NesTextEdit::new( + Range::new(Position::new(5, 0), Position::new(5, 10)), + "let result = helper();", + )], + )), + NesSuggestion::Jump(NesJumpSuggestion::new( + "sugg_002", + "file:///path/to/other.rs", + Position::new(10, 0), + )), + ]); + + let json = serde_json::to_value(&response).unwrap(); + assert_eq!(json["suggestions"].as_array().unwrap().len(), 2); + assert_eq!(json["suggestions"][0]["kind"], "edit"); + assert_eq!(json["suggestions"][1]["kind"], "jump"); + } +} diff --git a/src/rpc.rs b/src/rpc.rs index 868087ee..4df1d484 100644 --- a/src/rpc.rs +++ b/src/rpc.rs @@ -324,6 +324,18 @@ impl Side for AgentSide { m if m == AGENT_METHOD_NAMES.session_prompt => serde_json::from_str(params.get()) .map(ClientRequest::PromptRequest) .map_err(Into::into), + #[cfg(feature = "unstable_nes")] + m if m == AGENT_METHOD_NAMES.nes_start => serde_json::from_str(params.get()) + .map(ClientRequest::StartNesRequest) + .map_err(Into::into), + #[cfg(feature = "unstable_nes")] + m if m == AGENT_METHOD_NAMES.nes_suggest => serde_json::from_str(params.get()) + .map(ClientRequest::SuggestNesRequest) + .map_err(Into::into), + #[cfg(feature = "unstable_nes")] + m if m == AGENT_METHOD_NAMES.nes_close => serde_json::from_str(params.get()) + .map(ClientRequest::CloseNesRequest) + .map_err(Into::into), _ => { if let Some(custom_method) = method.strip_prefix('_') { Ok(ClientRequest::ExtMethodRequest(ExtRequest { @@ -344,6 +356,34 @@ impl Side for AgentSide { m if m == AGENT_METHOD_NAMES.session_cancel => serde_json::from_str(params.get()) .map(ClientNotification::CancelNotification) .map_err(Into::into), + #[cfg(feature = "unstable_nes")] + m if m == AGENT_METHOD_NAMES.document_did_open => serde_json::from_str(params.get()) + .map(ClientNotification::DidOpenDocumentNotification) + .map_err(Into::into), + #[cfg(feature = "unstable_nes")] + m if m == AGENT_METHOD_NAMES.document_did_change => serde_json::from_str(params.get()) + .map(ClientNotification::DidChangeDocumentNotification) + .map_err(Into::into), + #[cfg(feature = "unstable_nes")] + m if m == AGENT_METHOD_NAMES.document_did_close => serde_json::from_str(params.get()) + .map(ClientNotification::DidCloseDocumentNotification) + .map_err(Into::into), + #[cfg(feature = "unstable_nes")] + m if m == AGENT_METHOD_NAMES.document_did_save => serde_json::from_str(params.get()) + .map(ClientNotification::DidSaveDocumentNotification) + .map_err(Into::into), + #[cfg(feature = "unstable_nes")] + m if m == AGENT_METHOD_NAMES.document_did_focus => serde_json::from_str(params.get()) + .map(ClientNotification::DidFocusDocumentNotification) + .map_err(Into::into), + #[cfg(feature = "unstable_nes")] + m if m == AGENT_METHOD_NAMES.nes_accept => serde_json::from_str(params.get()) + .map(ClientNotification::AcceptNesNotification) + .map_err(Into::into), + #[cfg(feature = "unstable_nes")] + m if m == AGENT_METHOD_NAMES.nes_reject => serde_json::from_str(params.get()) + .map(ClientNotification::RejectNesNotification) + .map_err(Into::into), _ => { if let Some(custom_method) = method.strip_prefix('_') { Ok(ClientNotification::ExtNotification(ExtNotification { @@ -412,6 +452,171 @@ mod tests { } } +#[cfg(feature = "unstable_nes")] +#[cfg(test)] +mod nes_rpc_tests { + use super::*; + use serde_json::json; + + #[test] + fn test_decode_nes_start_request() { + let params = serde_json::to_string(&json!({ + "workspaceUri": "file:///Users/alice/projects/my-app", + "workspaceFolders": [ + { "uri": "file:///Users/alice/projects/my-app", "name": "my-app" } + ] + })) + .unwrap(); + let raw = serde_json::value::RawValue::from_string(params).unwrap(); + let request = AgentSide::decode_request("nes/start", Some(&raw)).unwrap(); + assert!(matches!(request, ClientRequest::StartNesRequest(_))); + } + + #[test] + fn test_decode_nes_suggest_request() { + let params = serde_json::to_string(&json!({ + "sessionId": "session_123", + "uri": "file:///path/to/file.rs", + "version": 2, + "position": { "line": 5, "character": 12 }, + "triggerKind": "automatic" + })) + .unwrap(); + let raw = serde_json::value::RawValue::from_string(params).unwrap(); + let request = AgentSide::decode_request("nes/suggest", Some(&raw)).unwrap(); + assert!(matches!(request, ClientRequest::SuggestNesRequest(_))); + } + + #[test] + fn test_decode_nes_close_request() { + let params = serde_json::to_string(&json!({ + "sessionId": "session_123" + })) + .unwrap(); + let raw = serde_json::value::RawValue::from_string(params).unwrap(); + let request = AgentSide::decode_request("nes/close", Some(&raw)).unwrap(); + assert!(matches!(request, ClientRequest::CloseNesRequest(_))); + } + + #[test] + fn test_decode_document_did_open_notification() { + let params = serde_json::to_string(&json!({ + "sessionId": "session_123", + "uri": "file:///path/to/file.rs", + "languageId": "rust", + "version": 1, + "text": "fn main() {}" + })) + .unwrap(); + let raw = serde_json::value::RawValue::from_string(params).unwrap(); + let notification = AgentSide::decode_notification("document/didOpen", Some(&raw)).unwrap(); + assert!(matches!( + notification, + ClientNotification::DidOpenDocumentNotification(_) + )); + } + + #[test] + fn test_decode_document_did_change_notification() { + let params = serde_json::to_string(&json!({ + "sessionId": "session_123", + "uri": "file:///path/to/file.rs", + "version": 2, + "contentChanges": [{ "text": "fn main() { let x = 1; }" }] + })) + .unwrap(); + let raw = serde_json::value::RawValue::from_string(params).unwrap(); + let notification = + AgentSide::decode_notification("document/didChange", Some(&raw)).unwrap(); + assert!(matches!( + notification, + ClientNotification::DidChangeDocumentNotification(_) + )); + } + + #[test] + fn test_decode_document_did_close_notification() { + let params = serde_json::to_string(&json!({ + "sessionId": "session_123", + "uri": "file:///path/to/file.rs" + })) + .unwrap(); + let raw = serde_json::value::RawValue::from_string(params).unwrap(); + let notification = AgentSide::decode_notification("document/didClose", Some(&raw)).unwrap(); + assert!(matches!( + notification, + ClientNotification::DidCloseDocumentNotification(_) + )); + } + + #[test] + fn test_decode_document_did_save_notification() { + let params = serde_json::to_string(&json!({ + "sessionId": "session_123", + "uri": "file:///path/to/file.rs" + })) + .unwrap(); + let raw = serde_json::value::RawValue::from_string(params).unwrap(); + let notification = AgentSide::decode_notification("document/didSave", Some(&raw)).unwrap(); + assert!(matches!( + notification, + ClientNotification::DidSaveDocumentNotification(_) + )); + } + + #[test] + fn test_decode_document_did_focus_notification() { + let params = serde_json::to_string(&json!({ + "sessionId": "session_123", + "uri": "file:///path/to/file.rs", + "version": 2, + "position": { "line": 5, "character": 12 }, + "visibleRange": { + "start": { "line": 0, "character": 0 }, + "end": { "line": 45, "character": 0 } + } + })) + .unwrap(); + let raw = serde_json::value::RawValue::from_string(params).unwrap(); + let notification = AgentSide::decode_notification("document/didFocus", Some(&raw)).unwrap(); + assert!(matches!( + notification, + ClientNotification::DidFocusDocumentNotification(_) + )); + } + + #[test] + fn test_decode_nes_accept_notification() { + let params = serde_json::to_string(&json!({ + "sessionId": "session_123", + "id": "sugg_001" + })) + .unwrap(); + let raw = serde_json::value::RawValue::from_string(params).unwrap(); + let notification = AgentSide::decode_notification("nes/accept", Some(&raw)).unwrap(); + assert!(matches!( + notification, + ClientNotification::AcceptNesNotification(_) + )); + } + + #[test] + fn test_decode_nes_reject_notification() { + let params = serde_json::to_string(&json!({ + "sessionId": "session_123", + "id": "sugg_001", + "reason": "rejected" + })) + .unwrap(); + let raw = serde_json::value::RawValue::from_string(params).unwrap(); + let notification = AgentSide::decode_notification("nes/reject", Some(&raw)).unwrap(); + assert!(matches!( + notification, + ClientNotification::RejectNesNotification(_) + )); + } +} + #[test] fn test_notification_wire_format() { use super::*;