From ec3762cd69481408c8afd46baff8fa34c11d7aa0 Mon Sep 17 00:00:00 2001 From: PsiACE Date: Mon, 31 Aug 2026 05:04:01 +0800 Subject: [PATCH 1/5] chore(schema): pin experimental v2 alpha schema --- schema/v2/VERSION | 1 + schema/v2/meta.json | 43 + schema/v2/schema.json | 11689 ++++++++++++++++++++++++++++++++++++++++ 3 files changed, 11733 insertions(+) create mode 100644 schema/v2/VERSION create mode 100644 schema/v2/meta.json create mode 100644 schema/v2/schema.json diff --git a/schema/v2/VERSION b/schema/v2/VERSION new file mode 100644 index 0000000..8f9b9d1 --- /dev/null +++ b/schema/v2/VERSION @@ -0,0 +1 @@ +refs/tags/schema-v2.0.0-alpha.3 diff --git a/schema/v2/meta.json b/schema/v2/meta.json new file mode 100644 index 0000000..47d7973 --- /dev/null +++ b/schema/v2/meta.json @@ -0,0 +1,43 @@ +{ + "version": 2, + "agentMethods": { + "initialize": "initialize", + "auth_login": "auth/login", + "providers_list": "providers/list", + "providers_set": "providers/set", + "providers_disable": "providers/disable", + "session_new": "session/new", + "session_set_config_option": "session/set_config_option", + "session_prompt": "session/prompt", + "session_cancel": "session/cancel", + "mcp_message": "mcp/message", + "session_list": "session/list", + "session_delete": "session/delete", + "session_fork": "session/fork", + "session_resume": "session/resume", + "session_close": "session/close", + "auth_logout": "auth/logout", + "nes_start": "nes/start", + "nes_suggest": "nes/suggest", + "nes_accept": "nes/accept", + "nes_reject": "nes/reject", + "nes_close": "nes/close", + "document_did_open": "document/didOpen", + "document_did_change": "document/didChange", + "document_did_close": "document/didClose", + "document_did_save": "document/didSave", + "document_did_focus": "document/didFocus" + }, + "clientMethods": { + "session_request_permission": "session/request_permission", + "session_update": "session/update", + "mcp_connect": "mcp/connect", + "mcp_message": "mcp/message", + "mcp_disconnect": "mcp/disconnect", + "elicitation_create": "elicitation/create", + "elicitation_complete": "elicitation/complete" + }, + "protocolMethods": { + "cancel_request": "$/cancel_request" + } +} diff --git a/schema/v2/schema.json b/schema/v2/schema.json new file mode 100644 index 0000000..c8b3810 --- /dev/null +++ b/schema/v2/schema.json @@ -0,0 +1,11689 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Agent Client Protocol", + "anyOf": [ + { + "title": "Agent", + "description": "A message (request, response, or notification) with `\"jsonrpc\": \"2.0\"` specified as\n[required by JSON-RPC 2.0 Specification][1].\n\n[1]: https://www.jsonrpc.org/specification#compatibility", + "type": "object", + "properties": { + "jsonrpc": { + "type": "string", + "enum": [ + "2.0" + ] + } + }, + "required": [ + "jsonrpc" + ], + "anyOf": [ + { + "title": "Request", + "allOf": [ + { + "$ref": "#/$defs/AgentRequest" + } + ] + }, + { + "title": "Response", + "allOf": [ + { + "$ref": "#/$defs/AgentResponse" + } + ] + }, + { + "title": "Notification", + "allOf": [ + { + "$ref": "#/$defs/AgentNotification" + } + ] + } + ] + }, + { + "title": "Client", + "description": "A message (request, response, or notification) with `\"jsonrpc\": \"2.0\"` specified as\n[required by JSON-RPC 2.0 Specification][1].\n\n[1]: https://www.jsonrpc.org/specification#compatibility", + "type": "object", + "properties": { + "jsonrpc": { + "type": "string", + "enum": [ + "2.0" + ] + } + }, + "required": [ + "jsonrpc" + ], + "anyOf": [ + { + "title": "Request", + "allOf": [ + { + "$ref": "#/$defs/ClientRequest" + } + ] + }, + { + "title": "Response", + "allOf": [ + { + "$ref": "#/$defs/ClientResponse" + } + ] + }, + { + "title": "Notification", + "allOf": [ + { + "$ref": "#/$defs/ClientNotification" + } + ] + } + ] + }, + { + "title": "AgentBatchCall", + "description": "A non-empty JSON-RPC 2.0 batch message.", + "type": "array", + "items": { + "description": "A message (request, response, or notification) with `\"jsonrpc\": \"2.0\"` specified as\n[required by JSON-RPC 2.0 Specification][1].\n\n[1]: https://www.jsonrpc.org/specification#compatibility", + "type": "object", + "properties": { + "jsonrpc": { + "type": "string", + "enum": [ + "2.0" + ] + } + }, + "required": [ + "jsonrpc" + ], + "anyOf": [ + { + "title": "Request", + "allOf": [ + { + "$ref": "#/$defs/AgentRequest" + } + ] + }, + { + "title": "Notification", + "allOf": [ + { + "$ref": "#/$defs/AgentNotification" + } + ] + }, + { + "title": "ProtocolLevelNotification", + "allOf": [ + { + "$ref": "#/$defs/ProtocolLevelNotification" + } + ] + } + ] + }, + "minItems": 1 + }, + { + "title": "AgentBatchResponse", + "description": "A non-empty JSON-RPC 2.0 batch message.", + "type": "array", + "items": { + "description": "A message (request, response, or notification) with `\"jsonrpc\": \"2.0\"` specified as\n[required by JSON-RPC 2.0 Specification][1].\n\n[1]: https://www.jsonrpc.org/specification#compatibility", + "type": "object", + "properties": { + "jsonrpc": { + "type": "string", + "enum": [ + "2.0" + ] + } + }, + "required": [ + "jsonrpc" + ], + "anyOf": [ + { + "title": "Result", + "description": "A successful JSON-RPC response.", + "type": "object", + "properties": { + "id": { + "description": "The id of the request this response answers.", + "allOf": [ + { + "$ref": "#/$defs/RequestId" + } + ] + }, + "result": { + "description": "Method-specific response data.", + "anyOf": [ + { + "title": "InitializeResponse", + "description": "Successful result returned for a `initialize` request.", + "allOf": [ + { + "$ref": "#/$defs/InitializeResponse" + } + ] + }, + { + "title": "LoginAuthResponse", + "description": "Successful result returned for an `auth/login` request.", + "allOf": [ + { + "$ref": "#/$defs/LoginAuthResponse" + } + ] + }, + { + "title": "ListProvidersResponse", + "description": "Successful result returned for a `providers/list` request.", + "allOf": [ + { + "$ref": "#/$defs/ListProvidersResponse" + } + ] + }, + { + "title": "SetProviderResponse", + "description": "Successful result returned for a `providers/set` request.", + "allOf": [ + { + "$ref": "#/$defs/SetProviderResponse" + } + ] + }, + { + "title": "DisableProviderResponse", + "description": "Successful result returned for a `providers/disable` request.", + "allOf": [ + { + "$ref": "#/$defs/DisableProviderResponse" + } + ] + }, + { + "title": "LogoutAuthResponse", + "description": "Successful result returned for an `auth/logout` request.", + "allOf": [ + { + "$ref": "#/$defs/LogoutAuthResponse" + } + ] + }, + { + "title": "NewSessionResponse", + "description": "Successful result returned for a `session/new` request.", + "allOf": [ + { + "$ref": "#/$defs/NewSessionResponse" + } + ] + }, + { + "title": "ListSessionsResponse", + "description": "Successful result returned for a `session/list` request.", + "allOf": [ + { + "$ref": "#/$defs/ListSessionsResponse" + } + ] + }, + { + "title": "DeleteSessionResponse", + "description": "Successful result returned for a `session/delete` request.", + "allOf": [ + { + "$ref": "#/$defs/DeleteSessionResponse" + } + ] + }, + { + "title": "ForkSessionResponse", + "description": "Successful result returned for a `session/fork` request.", + "allOf": [ + { + "$ref": "#/$defs/ForkSessionResponse" + } + ] + }, + { + "title": "ResumeSessionResponse", + "description": "Successful result returned for a `session/resume` request.", + "allOf": [ + { + "$ref": "#/$defs/ResumeSessionResponse" + } + ] + }, + { + "title": "CloseSessionResponse", + "description": "Successful result returned for a `session/close` request.", + "allOf": [ + { + "$ref": "#/$defs/CloseSessionResponse" + } + ] + }, + { + "title": "SetSessionConfigOptionResponse", + "description": "Successful result returned for a `session/set_config_option` request.", + "allOf": [ + { + "$ref": "#/$defs/SetSessionConfigOptionResponse" + } + ] + }, + { + "title": "PromptResponse", + "description": "Successful result returned for a `session/prompt` request.", + "allOf": [ + { + "$ref": "#/$defs/PromptResponse" + } + ] + }, + { + "title": "StartNesResponse", + "description": "Successful result returned for a `nes/start` request.", + "allOf": [ + { + "$ref": "#/$defs/StartNesResponse" + } + ] + }, + { + "title": "SuggestNesResponse", + "description": "Successful result returned for a `nes/suggest` request.", + "allOf": [ + { + "$ref": "#/$defs/SuggestNesResponse" + } + ] + }, + { + "title": "CloseNesResponse", + "description": "Successful result returned for a `nes/close` request.", + "allOf": [ + { + "$ref": "#/$defs/CloseNesResponse" + } + ] + }, + { + "title": "ExtMethodResponse", + "description": "Successful result returned by an extension method outside the core ACP method set.", + "allOf": [ + { + "$ref": "#/$defs/ExtResponse" + } + ] + }, + { + "title": "MessageMcpResponse", + "description": "Successful result returned by an MCP-over-ACP `mcp/message` request.", + "allOf": [ + { + "$ref": "#/$defs/MessageMcpResponse" + } + ] + } + ] + } + }, + "required": [ + "id", + "result" + ] + }, + { + "title": "Error", + "description": "A failed JSON-RPC response.", + "type": "object", + "properties": { + "id": { + "description": "The id of the request this response answers.", + "allOf": [ + { + "$ref": "#/$defs/RequestId" + } + ] + }, + "error": { + "description": "Method-specific error data.", + "allOf": [ + { + "$ref": "#/$defs/Error" + } + ] + } + }, + "required": [ + "id", + "error" + ] + } + ], + "x-docs-ignore": true + }, + "minItems": 1 + }, + { + "title": "ClientBatchCall", + "description": "A non-empty JSON-RPC 2.0 batch message.", + "type": "array", + "items": { + "description": "A message (request, response, or notification) with `\"jsonrpc\": \"2.0\"` specified as\n[required by JSON-RPC 2.0 Specification][1].\n\n[1]: https://www.jsonrpc.org/specification#compatibility", + "type": "object", + "properties": { + "jsonrpc": { + "type": "string", + "enum": [ + "2.0" + ] + } + }, + "required": [ + "jsonrpc" + ], + "anyOf": [ + { + "title": "Request", + "allOf": [ + { + "$ref": "#/$defs/ClientRequest" + } + ] + }, + { + "title": "Notification", + "allOf": [ + { + "$ref": "#/$defs/ClientNotification" + } + ] + }, + { + "title": "ProtocolLevelNotification", + "allOf": [ + { + "$ref": "#/$defs/ProtocolLevelNotification" + } + ] + } + ] + }, + "minItems": 1 + }, + { + "title": "ClientBatchResponse", + "description": "A non-empty JSON-RPC 2.0 batch message.", + "type": "array", + "items": { + "description": "A message (request, response, or notification) with `\"jsonrpc\": \"2.0\"` specified as\n[required by JSON-RPC 2.0 Specification][1].\n\n[1]: https://www.jsonrpc.org/specification#compatibility", + "type": "object", + "properties": { + "jsonrpc": { + "type": "string", + "enum": [ + "2.0" + ] + } + }, + "required": [ + "jsonrpc" + ], + "anyOf": [ + { + "title": "Result", + "description": "A successful JSON-RPC response.", + "type": "object", + "properties": { + "id": { + "description": "The id of the request this response answers.", + "allOf": [ + { + "$ref": "#/$defs/RequestId" + } + ] + }, + "result": { + "description": "Method-specific response data.", + "anyOf": [ + { + "title": "RequestPermissionResponse", + "description": "Successful result returned for a `session/request_permission` request.", + "allOf": [ + { + "$ref": "#/$defs/RequestPermissionResponse" + } + ] + }, + { + "title": "CreateElicitationResponse", + "description": "Successful result returned for a `elicitation/create` request.", + "allOf": [ + { + "$ref": "#/$defs/CreateElicitationResponse" + } + ] + }, + { + "title": "ConnectMcpResponse", + "description": "Successful result returned for a `mcp/connect` request.", + "allOf": [ + { + "$ref": "#/$defs/ConnectMcpResponse" + } + ] + }, + { + "title": "DisconnectMcpResponse", + "description": "Successful result returned for a `mcp/disconnect` request.", + "allOf": [ + { + "$ref": "#/$defs/DisconnectMcpResponse" + } + ] + }, + { + "title": "MessageMcpResponse", + "description": "Successful result returned by an MCP-over-ACP `mcp/message` request.", + "allOf": [ + { + "$ref": "#/$defs/MessageMcpResponse" + } + ] + }, + { + "title": "ExtMethodResponse", + "description": "Successful result returned by an extension method outside the core ACP method set.", + "allOf": [ + { + "$ref": "#/$defs/ExtResponse" + } + ] + } + ] + } + }, + "required": [ + "id", + "result" + ] + }, + { + "title": "Error", + "description": "A failed JSON-RPC response.", + "type": "object", + "properties": { + "id": { + "description": "The id of the request this response answers.", + "allOf": [ + { + "$ref": "#/$defs/RequestId" + } + ] + }, + "error": { + "description": "Method-specific error data.", + "allOf": [ + { + "$ref": "#/$defs/Error" + } + ] + } + }, + "required": [ + "id", + "error" + ] + } + ], + "x-docs-ignore": true + }, + "minItems": 1 + }, + { + "title": "ProtocolLevel", + "description": "A message (request, response, or notification) with `\"jsonrpc\": \"2.0\"` specified as\n[required by JSON-RPC 2.0 Specification][1].\n\n[1]: https://www.jsonrpc.org/specification#compatibility", + "type": "object", + "properties": { + "jsonrpc": { + "type": "string", + "enum": [ + "2.0" + ] + }, + "method": { + "description": "The notification method name.", + "type": "string" + }, + "params": { + "description": "Method-specific notification parameters.", + "anyOf": [ + { + "description": "General protocol-level notifications that all sides are expected to\nimplement.\n\nNotifications whose methods start with '$/' are messages which\nare protocol implementation dependent and might not be implementable in all\nclients or agents. For example if the implementation uses a single threaded\nsynchronous programming language then there is little it can do to react to\na `$/cancel_request` notification. If an agent or client receives\nnotifications starting with '$/' it is free to ignore the notification.\n\nNotifications do not expect a response.", + "anyOf": [ + { + "title": "CancelRequestNotification", + "description": "Cancels an ongoing request.\n\nThis is a notification sent by the side that sent a request to cancel that request.\n\nUpon receiving this notification, the receiver:\n\n1. MAY cancel the corresponding request activity and all nested activities\n2. MAY send any pending notifications.\n3. MUST send one of these responses for the original request:\n - Valid response with appropriate data (partial results or cancellation marker)\n - Error response with code `-32800` (Cancelled)\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/draft/cancellation)", + "allOf": [ + { + "$ref": "#/$defs/CancelRequestNotification" + } + ] + } + ] + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "jsonrpc", + "method" + ], + "x-docs-ignore": true + } + ], + "$defs": { + "AgentRequest": { + "description": "A JSON-RPC request object.", + "type": "object", + "properties": { + "id": { + "description": "The request id used to correlate the matching response.", + "allOf": [ + { + "$ref": "#/$defs/RequestId" + } + ] + }, + "method": { + "description": "The method name to invoke.", + "type": "string" + }, + "params": { + "description": "Method-specific request parameters.", + "anyOf": [ + { + "description": "All possible requests that an agent can send to a client.\n\nThis enum is used internally for routing RPC requests. You typically won't need\nto use this directly.\n\nThis enum encompasses all method calls from agent to client.", + "anyOf": [ + { + "title": "RequestPermissionRequest", + "description": "Requests permission from the user for an operation.\n\nCalled by the agent when it needs user authorization before executing\na potentially sensitive operation. The client should present the options\nto the user and return their decision.\n\nIf the client cancels active session work via `session/cancel`, it MUST\nrespond to this request with `RequestPermissionOutcome::Cancelled`.\n\nSee protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/v2/draft/tool-calls#requesting-permission)", + "allOf": [ + { + "$ref": "#/$defs/RequestPermissionRequest" + } + ] + }, + { + "title": "CreateElicitationRequest", + "description": "Requests structured user input via a form or URL.\n\nSee protocol docs: [Elicitation](https://agentclientprotocol.com/protocol/v2/draft/elicitation)", + "allOf": [ + { + "$ref": "#/$defs/CreateElicitationRequest" + } + ] + }, + { + "title": "ConnectMcpRequest", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nOpens an MCP-over-ACP connection.", + "allOf": [ + { + "$ref": "#/$defs/ConnectMcpRequest" + } + ] + }, + { + "title": "MessageMcpRequest", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nExchanges an MCP-over-ACP message.", + "allOf": [ + { + "$ref": "#/$defs/MessageMcpRequest" + } + ] + }, + { + "title": "DisconnectMcpRequest", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCloses an MCP-over-ACP connection.", + "allOf": [ + { + "$ref": "#/$defs/DisconnectMcpRequest" + } + ] + }, + { + "title": "ExtMethodRequest", + "description": "Handles extension method requests from the agent.\n\nAllows the Agent to send an arbitrary request that is not part of the ACP spec.\nExtension methods provide a way to add custom functionality while maintaining\nprotocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "allOf": [ + { + "$ref": "#/$defs/ExtRequest" + } + ] + } + ] + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "id", + "method" + ], + "x-docs-ignore": true + }, + "RequestId": { + "description": "JSON RPC Request Id\n\nAn identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification. The value SHOULD normally not be Null \\[1\\] and Numbers SHOULD NOT contain fractional parts \\[2\\]\n\nThe Server MUST reply with the same value in the Response object if included. This member is used to correlate the context between the two objects.\n\n\\[1\\] The use of Null as a value for the id member in a Request object is discouraged, because this specification uses a value of Null for Responses with an unknown id. Also, because JSON-RPC 1.0 uses an id value of Null for Notifications this could cause confusion in handling.\n\n\\[2\\] Fractional parts may be problematic, since many decimal fractions cannot be represented exactly as binary fractions.", + "anyOf": [ + { + "title": "Null", + "description": "The JSON-RPC `null` request id.", + "type": "null" + }, + { + "title": "Number", + "description": "A numeric JSON-RPC request id.", + "type": "integer", + "format": "int64" + }, + { + "title": "Str", + "description": "A string JSON-RPC request id.", + "type": "string" + } + ] + }, + "RequestPermissionRequest": { + "description": "Request for user permission to proceed with an operation.\n\nSent when the agent needs authorization before performing a sensitive operation.\n\nSee protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/v2/draft/tool-calls#requesting-permission)", + "type": "object", + "properties": { + "sessionId": { + "description": "The session ID for this request.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "title": { + "description": "Human-readable title for the permission prompt.\n\nThis title is specific to the permission prompt and does not update any\nsubject's displayed title.", + "type": "string" + }, + "description": { + "description": "Optional human-readable explanation of why permission is needed.\n\nThis text is specific to the permission prompt and does not update any\nsubject's displayed content. Omitted or `null` both mean no separate\npermission description was provided.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "subject": { + "description": "Optional structured context about the operation requiring permission.\n\nOmitted or `null` both mean no structured subject was provided.", + "anyOf": [ + { + "$ref": "#/$defs/RequestPermissionSubject" + }, + { + "type": "null" + } + ] + }, + "options": { + "description": "Available permission options for the user to choose from.\nMust contain at least one option.", + "type": "array", + "items": { + "$ref": "#/$defs/PermissionOption" + }, + "minItems": 1 + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId", + "title", + "options" + ], + "x-side": "client", + "x-method": "session/request_permission" + }, + "SessionId": { + "description": "A unique identifier for a conversation session between a client and agent.\n\nSessions maintain their own context, conversation history, and state,\nallowing multiple independent interactions with the same agent.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/v2/draft/session-setup#session-id)", + "type": "string" + }, + "RequestPermissionSubject": { + "description": "The operation requiring permission.", + "anyOf": [ + { + "description": "Permission is requested before executing a tool call.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "tool_call" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/ToolCallPermissionSubject" + } + ] + }, + { + "description": "Permission is requested before running a command.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "command" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/CommandPermissionSubject" + } + ] + }, + { + "title": "other", + "description": "Custom or future permission subject.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.\n\nClients that do not understand this subject type should preserve the raw\npayload when storing, replaying, proxying, or forwarding permission\nrequests, and otherwise display a generic permission prompt or decline it\naccording to policy.", + "type": "object", + "properties": { + "type": { + "description": "Custom or future permission subject type.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + }, + "required": [ + "type" + ], + "not": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "tool_call" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "command" + } + }, + "required": [ + "type" + ] + } + ] + }, + "additionalProperties": true + } + ] + }, + "ToolCallUpdate": { + "description": "Represents an upsert for a tool call that the language model has requested.\n\nTool calls are actions that the agent executes on behalf of the language model,\nsuch as reading files, executing code, or fetching data from external sources.\n\nOnly [`ToolCallUpdate::tool_call_id`] is required. Other fields have patch semantics:\nomitted fields leave the existing tool call value unchanged, `null` clears or\nunsets the value, and concrete values replace the previous value. For\ncollection fields, concrete arrays replace the previous collection, and both\n`null` and `[]` clear the collection. When a client receives a tool call ID it\nhas not seen before, omitted fields use client defaults.\n\nSee protocol docs: [Tool Calls](https://agentclientprotocol.com/protocol/v2/draft/tool-calls)", + "type": "object", + "properties": { + "toolCallId": { + "description": "Unique identifier for this tool call within the session.", + "allOf": [ + { + "$ref": "#/$defs/ToolCallId" + } + ] + }, + "name": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nProgrammatic name of the tool being invoked.\n\nThis field is optional and has patch semantics. Omission means no\nchange, `null` clears the name, and a string replaces it. For a tool\ncall ID the client has not seen before, omission or `null` means that no\ntool name is available.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "title": { + "description": "Human-readable title describing what the tool is doing.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "kind": { + "description": "The category of tool being invoked.\nHelps clients choose appropriate icons and UI treatment.", + "anyOf": [ + { + "$ref": "#/$defs/ToolKind" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "status": { + "description": "Current execution status of the tool call.", + "anyOf": [ + { + "$ref": "#/$defs/ToolCallStatus" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "content": { + "description": "Content produced by the tool call.", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/$defs/ToolCallContent" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "locations": { + "description": "File locations affected by this tool call.\nEnables \"follow-along\" features in clients.", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/$defs/ToolCallLocation" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "rawInput": { + "description": "Raw input parameters sent to the tool.", + "x-deserialize-default-on-error": true + }, + "rawOutput": { + "description": "Raw output returned by the tool.", + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted means no metadata update; `null` is an\nexplicit clear signal. Implementations MUST NOT make assumptions about values at these keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "toolCallId" + ] + }, + "ToolCallId": { + "description": "Unique identifier for a tool call within a session.", + "type": "string" + }, + "ToolKind": { + "description": "Categories of tools that can be invoked.\n\nTool kinds help clients choose appropriate icons and optimize how they\ndisplay tool execution progress.\n\nSee protocol docs: [Creating](https://agentclientprotocol.com/protocol/v2/draft/tool-calls#creating)", + "anyOf": [ + { + "description": "Reading files or data.", + "type": "string", + "const": "read" + }, + { + "description": "Modifying files or content.", + "type": "string", + "const": "edit" + }, + { + "description": "Removing files or data.", + "type": "string", + "const": "delete" + }, + { + "description": "Moving or renaming files.", + "type": "string", + "const": "move" + }, + { + "description": "Searching for information.", + "type": "string", + "const": "search" + }, + { + "description": "Running commands or code.", + "type": "string", + "const": "execute" + }, + { + "description": "Internal reasoning or planning.", + "type": "string", + "const": "think" + }, + { + "description": "Retrieving external data.", + "type": "string", + "const": "fetch" + }, + { + "description": "Switching the current session mode.", + "type": "string", + "const": "switch_mode" + }, + { + "description": "Other tool types (default).", + "type": "string", + "const": "other" + }, + { + "title": "unknown", + "description": "Custom or future tool kind.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + ] + }, + "ToolCallStatus": { + "description": "Execution status of a tool call.\n\nTool calls progress through different statuses during their lifecycle.\n\nSee protocol docs: [Status](https://agentclientprotocol.com/protocol/v2/draft/tool-calls#status)", + "anyOf": [ + { + "description": "The tool call hasn't started running yet because the input is either\nstreaming or we're awaiting approval.", + "type": "string", + "const": "pending" + }, + { + "description": "The tool call is currently running.", + "type": "string", + "const": "in_progress" + }, + { + "description": "The tool call completed successfully.", + "type": "string", + "const": "completed" + }, + { + "description": "The tool call failed with an error.", + "type": "string", + "const": "failed" + }, + { + "description": "The tool call was cancelled before it completed.", + "type": "string", + "const": "cancelled" + }, + { + "title": "other", + "description": "Custom or future tool call status.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + ] + }, + "ToolCallContent": { + "description": "Content produced by a tool call.\n\nTool calls can produce different types of content including standard\ncontent blocks (text, images), file diffs, or display-only terminals.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/v2/draft/tool-calls#content)", + "anyOf": [ + { + "description": "Standard content block (text, images, resources).", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "content" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/Content" + } + ] + }, + { + "description": "File modification shown as a diff.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "diff" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/Diff" + } + ] + }, + { + "description": "A display-only reference to an agent-owned terminal.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "terminal" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/Terminal" + } + ] + }, + { + "title": "other", + "description": "Custom or future tool call content.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.\n\nReceivers that do not understand this content type should preserve the\nraw payload when storing, replaying, proxying, or forwarding tool call\noutput, and otherwise ignore it or display it generically.", + "type": "object", + "properties": { + "type": { + "description": "Custom or future tool call content type.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + }, + "required": [ + "type" + ], + "not": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "content" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "diff" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "terminal" + } + }, + "required": [ + "type" + ] + } + ] + }, + "additionalProperties": true + } + ] + }, + "ContentBlock": { + "description": "Content blocks represent displayable information in the Agent Client Protocol.\n\nThey provide a structured way to handle various types of user-facing content\u2014whether\nit's text from language models, images for analysis, or embedded resources for context.\n\nContent blocks appear in:\n- User prompts sent via `session/prompt`\n- Language model output reported through `session/update` notifications as\n message updates or streamed chunks\n- Progress updates and results from tool calls\n\nThis structure is compatible with the Model Context Protocol (MCP), enabling\nagents to seamlessly forward content from MCP tool outputs without transformation.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/v2/draft/content)", + "anyOf": [ + { + "description": "Text content. May be plain text or formatted with Markdown.\n\nAll agents MUST support text content blocks in prompts.\nClients SHOULD render this text as Markdown.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "text" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/TextContent" + } + ] + }, + { + "description": "Images for visual context or analysis.\n\nRequires the `image` prompt capability when included in prompts.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "image" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/ImageContent" + } + ] + }, + { + "description": "Audio data for transcription or analysis.\n\nRequires the `audio` prompt capability when included in prompts.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "audio" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/AudioContent" + } + ] + }, + { + "description": "References to resources that the agent can access.\n\nAll agents MUST support resource links in prompts.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "resource_link" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/ResourceLink" + } + ] + }, + { + "description": "Complete resource contents embedded directly in the message.\n\nPreferred for including context as it avoids extra round-trips.\n\nRequires the `embeddedContext` prompt capability when included in prompts.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "resource" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/EmbeddedResource" + } + ] + }, + { + "title": "other", + "description": "Custom or future content block.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.\n\nReceivers that do not understand this content block type should preserve\nthe raw payload when storing, replaying, proxying, or forwarding content,\nand otherwise ignore it or display it generically.", + "type": "object", + "properties": { + "type": { + "description": "Custom or future content block type.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + }, + "required": [ + "type" + ], + "not": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "text" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "image" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "audio" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "resource_link" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "resource" + } + }, + "required": [ + "type" + ] + } + ] + }, + "additionalProperties": true + } + ] + }, + "Annotations": { + "description": "Optional annotations for the client. The client can use annotations to inform how objects are used or displayed", + "type": "object", + "properties": { + "audience": { + "description": "Intended recipients for this content, such as the user or assistant.", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/$defs/Role" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "lastModified": { + "description": "Timestamp indicating when the underlying resource was last modified.\n\nMust be an RFC 3339 formatted string (e.g., \"2025-01-12T15:00:58Z\").", + "type": [ + "string", + "null" + ], + "format": "date-time", + "x-deserialize-default-on-error": true + }, + "priority": { + "description": "Relative importance of this content when clients choose what to surface.", + "type": [ + "number", + "null" + ], + "format": "double", + "minimum": 0, + "maximum": 1, + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "Role": { + "description": "The sender or recipient of messages and data in a conversation.", + "anyOf": [ + { + "description": "The assistant side of a conversation.", + "type": "string", + "const": "assistant" + }, + { + "description": "The user side of a conversation.", + "type": "string", + "const": "user" + }, + { + "title": "other", + "description": "Custom or future role.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + ] + }, + "TextContent": { + "description": "Text provided to or from an LLM.", + "type": "object", + "properties": { + "text": { + "description": "Text payload carried by this content block.", + "type": "string" + }, + "annotations": { + "description": "Optional annotations that help clients decide how to display or route this content.", + "anyOf": [ + { + "$ref": "#/$defs/Annotations" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "text" + ] + }, + "MediaType": { + "description": "An Internet media type identifying the format of protocol content.", + "type": "string" + }, + "ImageContent": { + "description": "An image provided to or from an LLM.", + "type": "object", + "properties": { + "data": { + "description": "Base64-encoded media payload.", + "type": "string", + "contentEncoding": "base64" + }, + "mimeType": { + "description": "MIME type describing the encoded media payload.", + "allOf": [ + { + "$ref": "#/$defs/MediaType" + } + ] + }, + "uri": { + "description": "URI associated with this resource or media payload.", + "type": [ + "string", + "null" + ], + "format": "uri", + "x-deserialize-default-on-error": true + }, + "annotations": { + "description": "Optional annotations that help clients decide how to display or route this content.", + "anyOf": [ + { + "$ref": "#/$defs/Annotations" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "data", + "mimeType" + ] + }, + "AudioContent": { + "description": "Audio provided to or from an LLM.", + "type": "object", + "properties": { + "data": { + "description": "Base64-encoded media payload.", + "type": "string", + "contentEncoding": "base64" + }, + "mimeType": { + "description": "MIME type describing the encoded media payload.", + "allOf": [ + { + "$ref": "#/$defs/MediaType" + } + ] + }, + "annotations": { + "description": "Optional annotations that help clients decide how to display or route this content.", + "anyOf": [ + { + "$ref": "#/$defs/Annotations" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "data", + "mimeType" + ] + }, + "Icon": { + "description": "An optionally-sized icon that can be displayed in a user interface.", + "type": "object", + "properties": { + "src": { + "description": "A standard URI pointing to an icon resource.", + "type": "string", + "format": "uri" + }, + "mimeType": { + "description": "Optional MIME type override if the source MIME type is missing or generic.", + "anyOf": [ + { + "$ref": "#/$defs/MediaType" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "sizes": { + "description": "Optional array of strings that specify sizes at which the icon can be used.\nEach string should be in `WxH` format (e.g., `\"48x48\"`, `\"96x96\"`) or\n`\"any\"` for scalable formats like SVG.\n\nIf not provided, the client should assume that the icon can be used at any size.", + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "theme": { + "description": "Optional theme this icon is designed for.", + "anyOf": [ + { + "$ref": "#/$defs/IconTheme" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + } + }, + "required": [ + "src" + ] + }, + "IconTheme": { + "description": "Theme an icon is designed for.", + "anyOf": [ + { + "description": "Icon designed for light backgrounds.", + "type": "string", + "const": "light" + }, + { + "description": "Icon designed for dark backgrounds.", + "type": "string", + "const": "dark" + }, + { + "title": "other", + "description": "Custom or future icon theme.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + ] + }, + "ResourceLink": { + "description": "A resource that the server is capable of reading, included in a prompt or tool call result.", + "type": "object", + "properties": { + "name": { + "description": "Human-readable name shown for this protocol object.", + "type": "string" + }, + "uri": { + "description": "URI associated with this resource or media payload.", + "type": "string", + "format": "uri" + }, + "title": { + "description": "Optional display title for end-user UI.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "description": { + "description": "Optional human-readable details shown with this protocol object.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "icons": { + "description": "Optional set of sized icons that the client can display in a user interface.", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/$defs/Icon" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "mimeType": { + "description": "MIME type describing the encoded media payload.", + "anyOf": [ + { + "$ref": "#/$defs/MediaType" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "size": { + "description": "Optional size of the linked resource in bytes, if known.", + "type": [ + "integer", + "null" + ], + "format": "int64", + "x-deserialize-default-on-error": true + }, + "annotations": { + "description": "Optional annotations that help clients decide how to display or route this content.", + "anyOf": [ + { + "$ref": "#/$defs/Annotations" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "name", + "uri" + ] + }, + "EmbeddedResourceResource": { + "description": "Resource content that can be embedded in a message.", + "anyOf": [ + { + "title": "TextResourceContents", + "description": "Text resource contents embedded directly in the message.", + "allOf": [ + { + "$ref": "#/$defs/TextResourceContents" + } + ] + }, + { + "title": "BlobResourceContents", + "description": "Binary resource contents embedded directly in the message.", + "allOf": [ + { + "$ref": "#/$defs/BlobResourceContents" + } + ] + } + ] + }, + "TextResourceContents": { + "description": "Text-based resource contents.", + "type": "object", + "properties": { + "text": { + "description": "Text payload carried by this content block.", + "type": "string" + }, + "uri": { + "description": "URI associated with this resource or media payload.", + "type": "string", + "format": "uri" + }, + "mimeType": { + "description": "MIME type describing the encoded media payload.", + "anyOf": [ + { + "$ref": "#/$defs/MediaType" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "text", + "uri" + ] + }, + "BlobResourceContents": { + "description": "Binary resource contents.", + "type": "object", + "properties": { + "blob": { + "description": "Base64-encoded bytes for a binary resource payload.", + "type": "string", + "contentEncoding": "base64" + }, + "uri": { + "description": "URI associated with this resource or media payload.", + "type": "string", + "format": "uri" + }, + "mimeType": { + "description": "MIME type describing the encoded media payload.", + "anyOf": [ + { + "$ref": "#/$defs/MediaType" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "blob", + "uri" + ] + }, + "EmbeddedResource": { + "description": "The contents of a resource, embedded into a prompt or tool call result.", + "type": "object", + "properties": { + "resource": { + "description": "Embedded resource payload, either text or binary data.", + "allOf": [ + { + "$ref": "#/$defs/EmbeddedResourceResource" + } + ] + }, + "annotations": { + "description": "Optional annotations that help clients decide how to display or route this content.", + "anyOf": [ + { + "$ref": "#/$defs/Annotations" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "resource" + ] + }, + "Content": { + "description": "Standard content block (text, images, resources).", + "type": "object", + "properties": { + "content": { + "description": "The actual content block.", + "allOf": [ + { + "$ref": "#/$defs/ContentBlock" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "content" + ] + }, + "DiffChange": { + "description": "One file-level change described by a [`Diff`].\n\nStructured change metadata lets clients identify affected files and\noperations without parsing the text patch.", + "type": "object", + "properties": { + "fileType": { + "description": "File content kind.\n\nOmitted or `null` means the content kind is unknown.", + "anyOf": [ + { + "$ref": "#/$defs/DiffFileType" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "mimeType": { + "description": "MIME type of the file contents.\n\nOmitted or `null` means the MIME type is unknown.", + "anyOf": [ + { + "$ref": "#/$defs/MediaType" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "anyOf": [ + { + "description": "A file was added.", + "type": "object", + "properties": { + "operation": { + "type": "string", + "const": "add" + } + }, + "required": [ + "operation" + ], + "allOf": [ + { + "$ref": "#/$defs/DiffPathChange" + } + ] + }, + { + "description": "A file was deleted.", + "type": "object", + "properties": { + "operation": { + "type": "string", + "const": "delete" + } + }, + "required": [ + "operation" + ], + "allOf": [ + { + "$ref": "#/$defs/DiffPathChange" + } + ] + }, + { + "description": "A file was modified in place.", + "type": "object", + "properties": { + "operation": { + "type": "string", + "const": "modify" + } + }, + "required": [ + "operation" + ], + "allOf": [ + { + "$ref": "#/$defs/DiffPathChange" + } + ] + }, + { + "description": "A file was moved or renamed.", + "type": "object", + "properties": { + "operation": { + "type": "string", + "const": "move" + } + }, + "required": [ + "operation" + ], + "allOf": [ + { + "$ref": "#/$defs/DiffPathPairChange" + } + ] + }, + { + "description": "A file was copied.", + "type": "object", + "properties": { + "operation": { + "type": "string", + "const": "copy" + } + }, + "required": [ + "operation" + ], + "allOf": [ + { + "$ref": "#/$defs/DiffPathPairChange" + } + ] + }, + { + "title": "other", + "description": "Custom or future file operation.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "object", + "properties": { + "operation": { + "description": "Custom or future file operation.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + }, + "required": [ + "operation" + ], + "not": { + "anyOf": [ + { + "type": "object", + "properties": { + "operation": { + "type": "string", + "const": "add" + } + }, + "required": [ + "operation" + ] + }, + { + "type": "object", + "properties": { + "operation": { + "type": "string", + "const": "delete" + } + }, + "required": [ + "operation" + ] + }, + { + "type": "object", + "properties": { + "operation": { + "type": "string", + "const": "modify" + } + }, + "required": [ + "operation" + ] + }, + { + "type": "object", + "properties": { + "operation": { + "type": "string", + "const": "move" + } + }, + "required": [ + "operation" + ] + }, + { + "type": "object", + "properties": { + "operation": { + "type": "string", + "const": "copy" + } + }, + "required": [ + "operation" + ] + } + ] + }, + "additionalProperties": true + } + ] + }, + "DiffFileType": { + "description": "Kind of file content represented by a diff change.", + "anyOf": [ + { + "description": "Text content.", + "type": "string", + "const": "text" + }, + { + "description": "Binary or otherwise non-text content.", + "type": "string", + "const": "binary" + }, + { + "description": "Directory entry.", + "type": "string", + "const": "directory" + }, + { + "description": "Symbolic link.", + "type": "string", + "const": "symlink" + }, + { + "title": "other", + "description": "Custom or future file type.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + ] + }, + "AbsolutePath": { + "description": "An absolute filesystem path used by the protocol.", + "type": "string" + }, + "DiffPathChange": { + "description": "Operation metadata for add, delete, and modify changes.", + "type": "object", + "properties": { + "path": { + "description": "Absolute path for the operation.", + "allOf": [ + { + "$ref": "#/$defs/AbsolutePath" + } + ] + } + }, + "required": [ + "path" + ] + }, + "DiffPathPairChange": { + "description": "Operation metadata for move and copy changes.", + "type": "object", + "properties": { + "oldPath": { + "description": "Absolute path before the operation.", + "allOf": [ + { + "$ref": "#/$defs/AbsolutePath" + } + ] + }, + "path": { + "description": "Absolute path after the operation.", + "allOf": [ + { + "$ref": "#/$defs/AbsolutePath" + } + ] + } + }, + "required": [ + "oldPath", + "path" + ] + }, + "DiffPatch": { + "description": "Renderable patch text and its format.", + "type": "object", + "properties": { + "format": { + "description": "Patch format. The only ACP-defined value is `git_patch`.", + "allOf": [ + { + "$ref": "#/$defs/DiffPatchFormat" + } + ] + }, + "text": { + "description": "Patch text in the format named by `format`.", + "type": "string" + } + }, + "required": [ + "format", + "text" + ] + }, + "DiffPatchFormat": { + "description": "Text patch format used by [`DiffPatch`].", + "anyOf": [ + { + "description": "One or more `diff --git` sections in Git's `--patch` (`-p`) text format.\n\nPaths MUST be absolute. Surrounding commit metadata and email envelopes\nMUST NOT be included.", + "type": "string", + "const": "git_patch" + }, + { + "title": "other", + "description": "Custom or future patch format.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + ] + }, + "Diff": { + "description": "File changes produced by a tool call.\n\n`changes` is authoritative for affected absolute paths and operations.\n`patch` optionally carries renderable text for some or all of those changes\nand MUST be consistent with `changes`. Agents SHOULD provide `patch` whenever\nfeasible. Clients MUST handle diffs where `patch` is omitted or `null`.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/v2/draft/tool-calls#content)", + "type": "object", + "properties": { + "changes": { + "description": "Structured file changes described by this diff.\n\nClients can use this field without parsing patch text to determine affected paths.", + "type": "array", + "items": { + "$ref": "#/$defs/DiffChange" + }, + "x-deserialize-skip-invalid-items": true + }, + "patch": { + "description": "Renderable patch text for some or all of the structured changes.\n\nAgents SHOULD provide patch text whenever feasible. Omitted or `null`\nmeans no renderable patch text was provided.", + "anyOf": [ + { + "$ref": "#/$defs/DiffPatch" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "changes" + ] + }, + "TerminalId": { + "description": "Unique identifier for an agent-owned terminal within a session.", + "type": "string" + }, + "Terminal": { + "description": "A display-only reference to an agent-owned terminal.\n\nTerminal state and output are delivered separately through\n[`TerminalUpdate`] and [`TerminalOutputChunk`].", + "type": "object", + "properties": { + "terminalId": { + "description": "The ID of the terminal to display.", + "allOf": [ + { + "$ref": "#/$defs/TerminalId" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys. This metadata is scoped to the content reference. Omitted\nand `null` are equivalent and mean no item metadata was provided.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "terminalId" + ] + }, + "ToolCallLocation": { + "description": "A file location being accessed or modified by a tool.\n\nEnables clients to implement \"follow-along\" features that track\nwhich files the agent is working with in real-time.\n\nSee protocol docs: [Following the Agent](https://agentclientprotocol.com/protocol/v2/draft/tool-calls#following-the-agent)", + "type": "object", + "properties": { + "path": { + "description": "The absolute file path being accessed or modified.", + "allOf": [ + { + "$ref": "#/$defs/AbsolutePath" + } + ] + }, + "line": { + "description": "Optional line number within the file.", + "type": [ + "integer", + "null" + ], + "format": "uint32", + "minimum": 0, + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "path" + ] + }, + "ToolCallPermissionSubject": { + "description": "Permission request details for a tool call.", + "type": "object", + "properties": { + "toolCall": { + "description": "Details about the tool call requiring permission.", + "allOf": [ + { + "$ref": "#/$defs/ToolCallUpdate" + } + ] + } + }, + "required": [ + "toolCall" + ] + }, + "CommandPermissionSubject": { + "description": "Permission request details for a command.", + "type": "object", + "properties": { + "command": { + "description": "The command that would be run if permission is granted.", + "type": "string" + }, + "cwd": { + "description": "The absolute working directory for the command.", + "allOf": [ + { + "$ref": "#/$defs/AbsolutePath" + } + ] + }, + "toolCallId": { + "description": "The associated tool call, when known. Omitted and `null` are equivalent.", + "anyOf": [ + { + "$ref": "#/$defs/ToolCallId" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "terminalId": { + "description": "The associated terminal, when already known. Omitted and `null` are equivalent.", + "anyOf": [ + { + "$ref": "#/$defs/TerminalId" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys. Omitted and `null` are equivalent and mean no subject metadata was provided.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "command", + "cwd" + ] + }, + "PermissionOption": { + "description": "An option presented to the user when requesting permission.", + "type": "object", + "properties": { + "optionId": { + "description": "Unique identifier for this permission option.", + "allOf": [ + { + "$ref": "#/$defs/PermissionOptionId" + } + ] + }, + "name": { + "description": "Human-readable label to display to the user.", + "type": "string" + }, + "kind": { + "description": "Hint about the nature of this permission option.", + "allOf": [ + { + "$ref": "#/$defs/PermissionOptionKind" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "optionId", + "name", + "kind" + ] + }, + "PermissionOptionId": { + "description": "Unique identifier for a permission option.", + "type": "string" + }, + "PermissionOptionKind": { + "description": "The type of permission option being presented to the user.\n\nHelps clients choose appropriate icons and UI treatment.", + "anyOf": [ + { + "description": "Allow this operation only this time.", + "type": "string", + "const": "allow_once" + }, + { + "description": "Allow this operation and remember the choice.", + "type": "string", + "const": "allow_always" + }, + { + "description": "Reject this operation only this time.", + "type": "string", + "const": "reject_once" + }, + { + "description": "Reject this operation and remember the choice.", + "type": "string", + "const": "reject_always" + }, + { + "title": "other", + "description": "Custom or future permission option kind.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + ] + }, + "CreateElicitationRequest": { + "description": "Request from the agent to elicit structured user input.\n\nThe agent sends this to the client to request information from the user,\neither via a form or by directing them to a URL.\nElicitations are tied to a session (optionally a tool call) or a request.", + "type": "object", + "properties": { + "message": { + "description": "A human-readable message describing what input is needed.", + "type": "string" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "anyOf": [ + { + "description": "Form-based elicitation where the client renders a form from the provided schema.", + "type": "object", + "properties": { + "mode": { + "type": "string", + "const": "form" + } + }, + "required": [ + "mode" + ], + "allOf": [ + { + "$ref": "#/$defs/ElicitationFormMode" + } + ] + }, + { + "description": "URL-based elicitation where the client directs the user to a URL.", + "type": "object", + "properties": { + "mode": { + "type": "string", + "const": "url" + } + }, + "required": [ + "mode" + ], + "allOf": [ + { + "$ref": "#/$defs/ElicitationUrlMode" + } + ] + }, + { + "title": "other", + "description": "Custom or future elicitation mode.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.\n\nClients that do not understand this mode should preserve the raw payload\nwhen storing, replaying, proxying, or forwarding elicitation requests.\nThey MUST NOT render it as a known elicitation mode.", + "type": "object", + "properties": { + "mode": { + "description": "Custom or future elicitation mode.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + }, + "required": [ + "mode" + ], + "anyOf": [ + { + "title": "Session", + "description": "Tied to a session, optionally to a specific tool call within that session.", + "allOf": [ + { + "$ref": "#/$defs/ElicitationSessionScope" + } + ] + }, + { + "title": "Request", + "description": "Tied to a specific JSON-RPC request outside of a session\n(e.g., during auth/configuration phases before any session is started).", + "allOf": [ + { + "$ref": "#/$defs/ElicitationRequestScope" + } + ] + } + ], + "unevaluatedProperties": true, + "not": { + "anyOf": [ + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "const": "form" + } + }, + "required": [ + "mode" + ] + }, + { + "type": "object", + "properties": { + "mode": { + "type": "string", + "const": "url" + } + }, + "required": [ + "mode" + ] + } + ] + } + } + ], + "required": [ + "message" + ], + "x-side": "client", + "x-method": "elicitation/create" + }, + "ElicitationSessionScope": { + "description": "Session-scoped elicitation, optionally tied to a specific tool call.\n\nWhen `tool_call_id` is set, the elicitation is tied to a specific tool call.\nThis is useful when an agent receives an elicitation from an MCP server\nduring a tool call and needs to redirect it to the user.", + "type": "object", + "properties": { + "sessionId": { + "description": "The session this elicitation is tied to.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "toolCallId": { + "description": "Optional tool call within the session.\n\nOptional. Omitted and `null` are equivalent and mean the elicitation is scoped to the\nsession without a specific tool call.", + "anyOf": [ + { + "$ref": "#/$defs/ToolCallId" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + } + }, + "required": [ + "sessionId" + ] + }, + "ElicitationRequestScope": { + "description": "Request-scoped elicitation, tied to a specific JSON-RPC request outside of a session\n(e.g., during auth/configuration phases before any session is started).", + "type": "object", + "properties": { + "requestId": { + "description": "The request this elicitation is tied to.", + "allOf": [ + { + "$ref": "#/$defs/RequestId" + } + ] + } + }, + "required": [ + "requestId" + ] + }, + "ElicitationSchema": { + "description": "Type-safe elicitation schema for requesting structured user input.\n\nThis represents a JSON Schema object with primitive-typed properties,\nas required by the elicitation specification.", + "type": "object", + "properties": { + "type": { + "description": "Type discriminator. Always `\"object\"`.", + "x-deserialize-default-on-error": true, + "default": "object", + "allOf": [ + { + "$ref": "#/$defs/ElicitationSchemaType" + } + ] + }, + "title": { + "description": "Optional title for the schema.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "properties": { + "description": "Property definitions (must be primitive types).", + "type": "object", + "default": {}, + "additionalProperties": { + "$ref": "#/$defs/ElicitationPropertySchema" + } + }, + "required": { + "description": "List of required property names.\n\nOptional. Omitted and `null` are equivalent and mean no property names are required.", + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + } + }, + "description": { + "description": "Optional description of what this schema represents.\n\nOptional. Omitted and `null` are equivalent and mean no schema description is provided.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "ElicitationSchemaType": { + "description": "Type discriminator for elicitation schemas.", + "oneOf": [ + { + "description": "Object schema type.", + "type": "string", + "const": "object" + } + ] + }, + "ElicitationPropertySchema": { + "description": "Property schema for elicitation form fields.\n\nEach variant corresponds to a JSON Schema `\"type\"` value.\nSingle-select enums use the `String` variant with `enum` or `oneOf` set.\nMulti-select enums use the `Array` variant.", + "anyOf": [ + { + "description": "String property (or single-select enum when `enum`/`oneOf` is set).", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "string" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/StringPropertySchema" + } + ] + }, + { + "description": "Number (floating-point) property.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "number" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/NumberPropertySchema" + } + ] + }, + { + "description": "Integer property.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "integer" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/IntegerPropertySchema" + } + ] + }, + { + "description": "Boolean property.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "boolean" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/BooleanPropertySchema" + } + ] + }, + { + "description": "Multi-select array property.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "array" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/MultiSelectPropertySchema" + } + ] + }, + { + "title": "other", + "description": "Custom or future elicitation property schema.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.\n\nClients that do not understand this property schema type should preserve\nthe raw schema when storing, replaying, proxying, or forwarding\nelicitation requests. They MUST NOT render it as a known input control.", + "type": "object", + "properties": { + "type": { + "description": "Custom or future elicitation property schema type.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + }, + "required": [ + "type" + ], + "not": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "string" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "number" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "integer" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "boolean" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "array" + } + }, + "required": [ + "type" + ] + } + ] + }, + "additionalProperties": true + } + ] + }, + "StringFormat": { + "description": "String format types for string properties in elicitation schemas.", + "anyOf": [ + { + "description": "Email address format.", + "type": "string", + "const": "email" + }, + { + "description": "URI format.", + "type": "string", + "const": "uri" + }, + { + "description": "Date format (YYYY-MM-DD).", + "type": "string", + "const": "date" + }, + { + "description": "Date-time format (RFC 3339).", + "type": "string", + "const": "date-time" + }, + { + "title": "other", + "description": "Custom or future string format.\n\nUnknown formats are preserved. Implementations that do not understand a\nformat should treat it as an annotation rather than rejecting the schema.", + "type": "string" + } + ] + }, + "EnumOption": { + "description": "A titled enum option with a const value, human-readable title, and optional description.", + "type": "object", + "properties": { + "const": { + "description": "The constant value for this option.", + "type": "string" + }, + "title": { + "description": "Human-readable title for this option.", + "type": "string" + }, + "description": { + "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "const", + "title" + ] + }, + "StringPropertySchema": { + "description": "Schema for string properties in an elicitation form.\n\nWhen `enum` or `oneOf` is set, this represents a single-select enum\nwith `\"type\": \"string\"`.", + "type": "object", + "properties": { + "title": { + "description": "Optional title for the property.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "description": { + "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "minLength": { + "description": "Minimum string length.\n\nOptional. Omitted and `null` are equivalent and mean there is no minimum length constraint.", + "type": [ + "integer", + "null" + ], + "format": "uint32", + "minimum": 0 + }, + "maxLength": { + "description": "Maximum string length.\n\nOptional. Omitted and `null` are equivalent and mean there is no maximum length constraint.", + "type": [ + "integer", + "null" + ], + "format": "uint32", + "minimum": 0 + }, + "pattern": { + "description": "Pattern the string must match.\n\nOptional. Omitted and `null` are equivalent and mean there is no pattern constraint.", + "type": [ + "string", + "null" + ], + "format": "regex" + }, + "format": { + "description": "String format.\n\nOptional. Omitted and `null` are equivalent and mean there is no format constraint.", + "anyOf": [ + { + "$ref": "#/$defs/StringFormat" + }, + { + "type": "null" + } + ] + }, + "default": { + "description": "Default value.\n\nOptional. Omitted and `null` are equivalent and mean no default value is provided.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "enum": { + "description": "Enum values for untitled single-select enums.\nMust contain at least one value when present.\nOptional. Omitted and `null` are equivalent and mean no untitled single-select choices are\ndeclared by `enum`.", + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + }, + "minItems": 1 + }, + "oneOf": { + "description": "Titled enum options for titled single-select enums.\nMust contain at least one option when present.\nOptional. Omitted and `null` are equivalent and mean no titled single-select choices are\ndeclared by `oneOf`.", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/$defs/EnumOption" + }, + "minItems": 1 + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "NumberPropertySchema": { + "description": "Schema for number (floating-point) properties in an elicitation form.", + "type": "object", + "properties": { + "title": { + "description": "Optional title for the property.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "description": { + "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "minimum": { + "description": "Minimum value (inclusive).\n\nOptional. Omitted and `null` are equivalent and mean there is no inclusive lower bound.", + "type": [ + "number", + "null" + ], + "format": "double" + }, + "maximum": { + "description": "Maximum value (inclusive).\n\nOptional. Omitted and `null` are equivalent and mean there is no inclusive upper bound.", + "type": [ + "number", + "null" + ], + "format": "double" + }, + "default": { + "description": "Default value.\n\nOptional. Omitted and `null` are equivalent and mean no default value is provided.", + "type": [ + "number", + "null" + ], + "format": "double", + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "IntegerPropertySchema": { + "description": "Schema for integer properties in an elicitation form.", + "type": "object", + "properties": { + "title": { + "description": "Optional title for the property.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "description": { + "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "minimum": { + "description": "Minimum value (inclusive).\n\nOptional. Omitted and `null` are equivalent and mean there is no inclusive lower bound.", + "type": [ + "integer", + "null" + ], + "format": "int64" + }, + "maximum": { + "description": "Maximum value (inclusive).\n\nOptional. Omitted and `null` are equivalent and mean there is no inclusive upper bound.", + "type": [ + "integer", + "null" + ], + "format": "int64" + }, + "default": { + "description": "Default value.\n\nOptional. Omitted and `null` are equivalent and mean no default value is provided.", + "type": [ + "integer", + "null" + ], + "format": "int64", + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "BooleanPropertySchema": { + "description": "Schema for boolean properties in an elicitation form.", + "type": "object", + "properties": { + "title": { + "description": "Optional title for the property.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "description": { + "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "default": { + "description": "Default value.\n\nOptional. Omitted and `null` are equivalent and mean no default value is provided.", + "type": [ + "boolean", + "null" + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "MultiSelectItems": { + "description": "Items for a multi-select (array) property schema.", + "anyOf": [ + { + "description": "Multi-select string items with plain string values.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "string" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/StringMultiSelectItems" + } + ] + }, + { + "title": "other", + "description": "Custom or future typed multi-select items.", + "type": "object", + "properties": { + "type": { + "description": "Custom or future multi-select item type.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + }, + "required": [ + "type" + ], + "not": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "string" + } + }, + "required": [ + "type" + ] + } + ] + }, + "additionalProperties": true + }, + { + "title": "titled", + "description": "Titled multi-select items with human-readable labels.", + "allOf": [ + { + "$ref": "#/$defs/TitledMultiSelectItems" + } + ] + } + ] + }, + "StringMultiSelectItems": { + "description": "String item schema for multi-select enum properties.", + "type": "object", + "properties": { + "enum": { + "description": "Allowed enum values. Must contain at least one value.", + "type": "array", + "items": { + "type": "string" + }, + "minItems": 1 + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "enum" + ] + }, + "TitledMultiSelectItems": { + "description": "Items definition for titled multi-select enum properties.", + "type": "object", + "properties": { + "anyOf": { + "description": "Titled enum options. Must contain at least one option.", + "type": "array", + "items": { + "$ref": "#/$defs/EnumOption" + }, + "minItems": 1 + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "anyOf" + ] + }, + "MultiSelectPropertySchema": { + "description": "Schema for multi-select (array) properties in an elicitation form.", + "type": "object", + "properties": { + "title": { + "description": "Optional title for the property.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "description": { + "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "minItems": { + "description": "Minimum number of items to select.\n\nOptional. Omitted and `null` are equivalent and mean there is no minimum selection count.", + "type": [ + "integer", + "null" + ], + "format": "uint64", + "minimum": 0 + }, + "maxItems": { + "description": "Maximum number of items to select.\n\nOptional. Omitted and `null` are equivalent and mean there is no maximum selection count.", + "type": [ + "integer", + "null" + ], + "format": "uint64", + "minimum": 0 + }, + "items": { + "description": "The items definition describing allowed values.", + "allOf": [ + { + "$ref": "#/$defs/MultiSelectItems" + } + ] + }, + "default": { + "description": "Default selected values.\n\nOptional. Omitted and `null` are equivalent and mean no default selections are provided.", + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "items" + ] + }, + "ElicitationFormMode": { + "description": "Form-based elicitation mode where the client renders a form from the provided schema.", + "type": "object", + "properties": { + "requestedSchema": { + "description": "A JSON Schema describing the form fields to present to the user.", + "allOf": [ + { + "$ref": "#/$defs/ElicitationSchema" + } + ] + } + }, + "anyOf": [ + { + "title": "Session", + "description": "Tied to a session, optionally to a specific tool call within that session.", + "allOf": [ + { + "$ref": "#/$defs/ElicitationSessionScope" + } + ] + }, + { + "title": "Request", + "description": "Tied to a specific JSON-RPC request outside of a session\n(e.g., during auth/configuration phases before any session is started).", + "allOf": [ + { + "$ref": "#/$defs/ElicitationRequestScope" + } + ] + } + ], + "required": [ + "requestedSchema" + ] + }, + "ElicitationId": { + "description": "Unique identifier for an elicitation.", + "type": "string" + }, + "ElicitationUrlMode": { + "description": "URL-based elicitation mode where the client directs the user to a URL.", + "type": "object", + "properties": { + "elicitationId": { + "description": "The unique identifier for this elicitation.", + "allOf": [ + { + "$ref": "#/$defs/ElicitationId" + } + ] + }, + "url": { + "description": "The URL to direct the user to.", + "type": "string", + "format": "uri" + } + }, + "anyOf": [ + { + "title": "Session", + "description": "Tied to a session, optionally to a specific tool call within that session.", + "allOf": [ + { + "$ref": "#/$defs/ElicitationSessionScope" + } + ] + }, + { + "title": "Request", + "description": "Tied to a specific JSON-RPC request outside of a session\n(e.g., during auth/configuration phases before any session is started).", + "allOf": [ + { + "$ref": "#/$defs/ElicitationRequestScope" + } + ] + } + ], + "required": [ + "elicitationId", + "url" + ] + }, + "ConnectMcpRequest": { + "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 `mcp/connect`.", + "type": "object", + "properties": { + "serverId": { + "description": "The ACP MCP server ID that was provided by the component declaring the MCP server.", + "allOf": [ + { + "$ref": "#/$defs/McpServerAcpId" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "serverId" + ], + "x-side": "client", + "x-method": "mcp/connect" + }, + "McpServerAcpId": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnique identifier for an MCP server using the ACP transport.\n\nThe value is opaque and generated by the ACP component providing the MCP server. It is\nused by `mcp/connect` to route connection requests back to the component that declared the\nserver.", + "type": "string" + }, + "MessageMcpRequest": { + "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 `mcp/message`.", + "type": "object", + "properties": { + "connectionId": { + "description": "The MCP-over-ACP connection this message is sent on.", + "allOf": [ + { + "$ref": "#/$defs/McpConnectionId" + } + ] + }, + "method": { + "description": "The inner MCP method name.", + "type": "string" + }, + "params": { + "description": "Optional inner MCP params.\n\nIf omitted or set to `null`, the inner MCP message has no params.", + "type": [ + "object", + "null" + ], + "additionalProperties": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "connectionId", + "method" + ], + "x-side": "both", + "x-method": "mcp/message" + }, + "McpConnectionId": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA unique identifier for an active MCP-over-ACP connection.", + "type": "string" + }, + "DisconnectMcpRequest": { + "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 `mcp/disconnect`.", + "type": "object", + "properties": { + "connectionId": { + "description": "The MCP-over-ACP connection to close.", + "allOf": [ + { + "$ref": "#/$defs/McpConnectionId" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "connectionId" + ], + "x-side": "client", + "x-method": "mcp/disconnect" + }, + "ExtRequest": { + "description": "Allows for sending an arbitrary request that is not part of the ACP spec.\nExtension methods provide a way to add custom functionality while maintaining\nprotocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)" + }, + "AgentResponse": { + "description": "A JSON-RPC response object.", + "anyOf": [ + { + "title": "Result", + "description": "A successful JSON-RPC response.", + "type": "object", + "properties": { + "id": { + "description": "The id of the request this response answers.", + "allOf": [ + { + "$ref": "#/$defs/RequestId" + } + ] + }, + "result": { + "description": "Method-specific response data.", + "anyOf": [ + { + "title": "InitializeResponse", + "description": "Successful result returned for a `initialize` request.", + "allOf": [ + { + "$ref": "#/$defs/InitializeResponse" + } + ] + }, + { + "title": "LoginAuthResponse", + "description": "Successful result returned for an `auth/login` request.", + "allOf": [ + { + "$ref": "#/$defs/LoginAuthResponse" + } + ] + }, + { + "title": "ListProvidersResponse", + "description": "Successful result returned for a `providers/list` request.", + "allOf": [ + { + "$ref": "#/$defs/ListProvidersResponse" + } + ] + }, + { + "title": "SetProviderResponse", + "description": "Successful result returned for a `providers/set` request.", + "allOf": [ + { + "$ref": "#/$defs/SetProviderResponse" + } + ] + }, + { + "title": "DisableProviderResponse", + "description": "Successful result returned for a `providers/disable` request.", + "allOf": [ + { + "$ref": "#/$defs/DisableProviderResponse" + } + ] + }, + { + "title": "LogoutAuthResponse", + "description": "Successful result returned for an `auth/logout` request.", + "allOf": [ + { + "$ref": "#/$defs/LogoutAuthResponse" + } + ] + }, + { + "title": "NewSessionResponse", + "description": "Successful result returned for a `session/new` request.", + "allOf": [ + { + "$ref": "#/$defs/NewSessionResponse" + } + ] + }, + { + "title": "ListSessionsResponse", + "description": "Successful result returned for a `session/list` request.", + "allOf": [ + { + "$ref": "#/$defs/ListSessionsResponse" + } + ] + }, + { + "title": "DeleteSessionResponse", + "description": "Successful result returned for a `session/delete` request.", + "allOf": [ + { + "$ref": "#/$defs/DeleteSessionResponse" + } + ] + }, + { + "title": "ForkSessionResponse", + "description": "Successful result returned for a `session/fork` request.", + "allOf": [ + { + "$ref": "#/$defs/ForkSessionResponse" + } + ] + }, + { + "title": "ResumeSessionResponse", + "description": "Successful result returned for a `session/resume` request.", + "allOf": [ + { + "$ref": "#/$defs/ResumeSessionResponse" + } + ] + }, + { + "title": "CloseSessionResponse", + "description": "Successful result returned for a `session/close` request.", + "allOf": [ + { + "$ref": "#/$defs/CloseSessionResponse" + } + ] + }, + { + "title": "SetSessionConfigOptionResponse", + "description": "Successful result returned for a `session/set_config_option` request.", + "allOf": [ + { + "$ref": "#/$defs/SetSessionConfigOptionResponse" + } + ] + }, + { + "title": "PromptResponse", + "description": "Successful result returned for a `session/prompt` request.", + "allOf": [ + { + "$ref": "#/$defs/PromptResponse" + } + ] + }, + { + "title": "StartNesResponse", + "description": "Successful result returned for a `nes/start` request.", + "allOf": [ + { + "$ref": "#/$defs/StartNesResponse" + } + ] + }, + { + "title": "SuggestNesResponse", + "description": "Successful result returned for a `nes/suggest` request.", + "allOf": [ + { + "$ref": "#/$defs/SuggestNesResponse" + } + ] + }, + { + "title": "CloseNesResponse", + "description": "Successful result returned for a `nes/close` request.", + "allOf": [ + { + "$ref": "#/$defs/CloseNesResponse" + } + ] + }, + { + "title": "ExtMethodResponse", + "description": "Successful result returned by an extension method outside the core ACP method set.", + "allOf": [ + { + "$ref": "#/$defs/ExtResponse" + } + ] + }, + { + "title": "MessageMcpResponse", + "description": "Successful result returned by an MCP-over-ACP `mcp/message` request.", + "allOf": [ + { + "$ref": "#/$defs/MessageMcpResponse" + } + ] + } + ] + } + }, + "required": [ + "id", + "result" + ] + }, + { + "title": "Error", + "description": "A failed JSON-RPC response.", + "type": "object", + "properties": { + "id": { + "description": "The id of the request this response answers.", + "allOf": [ + { + "$ref": "#/$defs/RequestId" + } + ] + }, + "error": { + "description": "Method-specific error data.", + "allOf": [ + { + "$ref": "#/$defs/Error" + } + ] + } + }, + "required": [ + "id", + "error" + ] + } + ], + "x-docs-ignore": true + }, + "InitializeResponse": { + "description": "Response to the `initialize` method.\n\nContains the negotiated protocol version and agent capabilities.\n\nSee protocol docs: [Initialization](https://agentclientprotocol.com/protocol/v2/draft/initialization)", + "type": "object", + "properties": { + "protocolVersion": { + "description": "The protocol version the client specified if supported by the agent,\nor the latest protocol version supported by the agent.\n\nThe client should disconnect, if it doesn't support this version.", + "allOf": [ + { + "$ref": "#/$defs/ProtocolVersion" + } + ] + }, + "info": { + "description": "Information about the implementation sending this initialize response.", + "allOf": [ + { + "$ref": "#/$defs/Implementation" + } + ] + }, + "capabilities": { + "description": "Capabilities supported by the agent.", + "x-deserialize-default-on-error": true, + "default": {}, + "allOf": [ + { + "$ref": "#/$defs/AgentCapabilities" + } + ] + }, + "authMethods": { + "description": "Authentication methods supported by the agent.\n\nOptional. Omitted or empty means the agent does not advertise the\nauthentication method surface. Supplying one or more valid methods means\nthe agent MUST support both `auth/login` and `auth/logout`.", + "type": "array", + "items": { + "$ref": "#/$defs/AuthMethod" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "protocolVersion", + "info" + ], + "x-side": "agent", + "x-method": "initialize" + }, + "ProtocolVersion": { + "description": "Protocol version identifier.\n\nThis version is only bumped for breaking changes.\nNon-breaking changes should be introduced via capabilities.", + "type": "integer", + "format": "uint16", + "minimum": 0, + "maximum": 65535 + }, + "Implementation": { + "description": "Metadata about the implementation of the client or agent.\nDescribes the name and version of an ACP implementation, with an optional\ntitle for UI representation.", + "type": "object", + "properties": { + "name": { + "description": "Intended for programmatic or logical use, but can be used as a display\nname fallback if title isn\u2019t present.", + "type": "string" + }, + "title": { + "description": "Intended for UI and end-user contexts \u2014 optimized to be human-readable\nand easily understood.\n\nIf not provided, the name should be used for display.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "version": { + "description": "Version of the implementation. Can be displayed to the user or used\nfor debugging or metrics purposes. (e.g. \"1.0.0\").", + "type": "string" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "name", + "version" + ] + }, + "AgentCapabilities": { + "description": "Capabilities supported by the agent.\n\nAdvertised during initialization to inform the client about\navailable features and content types.\n\nSee protocol docs: [Agent Capabilities](https://agentclientprotocol.com/protocol/v2/draft/initialization#agent-capabilities)", + "type": "object", + "properties": { + "session": { + "description": "Session capabilities supported by the agent.\n\nOptional. Omitted or `null` both mean the agent does not support the\n`session/*` method surface. Supplying `{}` means the agent supports the\nbaseline session methods: `session/new`, `session/prompt`,\n`session/cancel`, and `session/update`.", + "anyOf": [ + { + "$ref": "#/$defs/SessionCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "auth": { + "description": "Authentication-related extension capabilities supported by the agent.\n\nOptional. Omitted or `null` both mean the agent does not advertise any\nauthentication-related extensions. This field does not advertise support\nfor `auth/login` or `auth/logout`; those methods are advertised by a\nnon-empty `authMethods` list in the `initialize` response.", + "anyOf": [ + { + "$ref": "#/$defs/AgentAuthCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "providers": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nProvider configuration capabilities supported by the agent.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports provider configuration methods.", + "anyOf": [ + { + "$ref": "#/$defs/ProvidersCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "nes": { + "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.\n\nOptional. Omitted or `null` both mean the agent does not advertise support\nfor NES methods.", + "anyOf": [ + { + "$ref": "#/$defs/NesCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "positionEncoding": { + "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.", + "anyOf": [ + { + "$ref": "#/$defs/PositionEncodingKind" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "SessionCapabilities": { + "description": "Session capabilities supported by the agent.\n\nSupplying `{}` means the agent supports the baseline session methods:\n`session/new`, `session/list`, `session/resume`, `session/close`,\n`session/prompt`, `session/cancel`, and `session/update`.\n\nAgents that support sessions **MAY** support additional session methods,\nprompt content types, and MCP transports by specifying additional\ncapabilities.\n\nSee protocol docs: [Session Capabilities](https://agentclientprotocol.com/protocol/v2/draft/initialization#session-capabilities)", + "type": "object", + "properties": { + "prompt": { + "description": "Prompt capabilities supported by the agent in `session/prompt` requests.\n\nOptional. Omitted or `null` both mean the agent does not advertise any\nprompt extensions beyond the baseline text and resource-link content\nrequired by `session/prompt`.", + "anyOf": [ + { + "$ref": "#/$defs/PromptCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "mcp": { + "description": "MCP capabilities supported by the agent for session lifecycle requests.\n\nOptional. Omitted or `null` both mean the agent does not advertise MCP\nserver transport support for sessions.", + "anyOf": [ + { + "$ref": "#/$defs/McpCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "delete": { + "description": "Whether the agent supports `session/delete`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports deleting sessions from `session/list`.", + "anyOf": [ + { + "$ref": "#/$defs/SessionDeleteCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "additionalDirectories": { + "description": "Whether the agent supports `additionalDirectories` on supported session lifecycle requests.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports `additionalDirectories` on\nsupported session lifecycle requests.\n\nAgents may return `SessionInfo.additionalDirectories` to report the\ncomplete ordered additional-root list associated with a listed session.", + "anyOf": [ + { + "$ref": "#/$defs/SessionAdditionalDirectoriesCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "fork": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhether the agent supports `session/fork`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports forking sessions.", + "anyOf": [ + { + "$ref": "#/$defs/SessionForkCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "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/v2/draft/initialization#prompt-capabilities)", + "type": "object", + "properties": { + "image": { + "description": "Agent supports [`ContentBlock::Image`].\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports image content in prompts.", + "anyOf": [ + { + "$ref": "#/$defs/PromptImageCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "audio": { + "description": "Agent supports [`ContentBlock::Audio`].\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports audio content in prompts.", + "anyOf": [ + { + "$ref": "#/$defs/PromptAudioCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "embeddedContext": { + "description": "Agent supports embedded context in `session/prompt` requests.\n\nWhen enabled, the Client is allowed to include [`ContentBlock::Resource`]\nin prompt requests for pieces of context that are referenced in the message.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports embedded context in prompts.", + "anyOf": [ + { + "$ref": "#/$defs/PromptEmbeddedContextCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "PromptImageCapabilities": { + "description": "Capabilities for image content in prompt requests.\n\nSupplying `{}` means the agent supports image content in prompts.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "PromptAudioCapabilities": { + "description": "Capabilities for audio content in prompt requests.\n\nSupplying `{}` means the agent supports audio content in prompts.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "PromptEmbeddedContextCapabilities": { + "description": "Capabilities for embedded context in prompt requests.\n\nSupplying `{}` means the agent supports embedded context in prompts.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "McpCapabilities": { + "description": "MCP capabilities supported by the agent for session lifecycle requests.", + "type": "object", + "properties": { + "stdio": { + "description": "Agent supports [`McpServer::Stdio`].\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports stdio MCP server transports.", + "anyOf": [ + { + "$ref": "#/$defs/McpStdioCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "http": { + "description": "Agent supports [`McpServer::Http`].\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports HTTP MCP server transports.", + "anyOf": [ + { + "$ref": "#/$defs/McpHttpCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "acp": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAgent supports [`McpServer::Acp`].\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports ACP MCP server transports.", + "anyOf": [ + { + "$ref": "#/$defs/McpAcpCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "McpStdioCapabilities": { + "description": "Capabilities for stdio MCP server transports.\n\nSupplying `{}` means the agent supports stdio MCP server transports.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "McpHttpCapabilities": { + "description": "Capabilities for HTTP MCP server transports.\n\nSupplying `{}` means the agent supports HTTP MCP server transports.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "McpAcpCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapabilities for ACP MCP server transports.\n\nSupplying `{}` means the agent supports ACP MCP server transports.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "SessionDeleteCapabilities": { + "description": "Capabilities for the `session/delete` method.\n\nSupplying `{}` means the agent supports deleting sessions from `session/list`.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "SessionAdditionalDirectoriesCapabilities": { + "description": "Capabilities for additional session directories support.\n\nSupplying `{}` means the agent supports the `additionalDirectories` field on\nsupported session lifecycle requests. Agents that also support\n`session/list` may return `SessionInfo.additionalDirectories` to report the\ncomplete ordered additional-root list associated with a listed session.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "SessionForkCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapabilities for the `session/fork` method.\n\nSupplying `{}` means the agent supports forking sessions.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "AgentAuthCapabilities": { + "description": "Authentication-related extension capabilities supported by the agent.\n\nThis object does not advertise support for `auth/login` or `auth/logout`.\nThose methods are advertised by a non-empty `authMethods` list in the\n`initialize` response.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "ProvidersCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nProvider configuration capabilities supported by the agent.\n\nSupplying `{}` means the agent supports provider configuration methods.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "NesCapabilities": { + "description": "NES capabilities advertised by the agent during initialization.\n\nSupplying `{}` means the agent supports the NES method surface. Omitted or\n`null` both mean the agent does not advertise support for `nes/*` methods.", + "type": "object", + "properties": { + "events": { + "description": "Events the agent wants to receive.", + "anyOf": [ + { + "$ref": "#/$defs/NesEventCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "context": { + "description": "Context the agent wants attached to each suggestion request.", + "anyOf": [ + { + "$ref": "#/$defs/NesContextCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "NesEventCapabilities": { + "description": "Event capabilities the agent can consume.", + "type": "object", + "properties": { + "document": { + "description": "Document event capabilities.", + "anyOf": [ + { + "$ref": "#/$defs/NesDocumentEventCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "NesDocumentEventCapabilities": { + "description": "Document event capabilities the agent wants to receive.", + "type": "object", + "properties": { + "didOpen": { + "description": "Whether the agent wants `document/didOpen` events.", + "anyOf": [ + { + "$ref": "#/$defs/NesDocumentDidOpenCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "didChange": { + "description": "Whether the agent wants `document/didChange` events, and the sync kind.", + "anyOf": [ + { + "$ref": "#/$defs/NesDocumentDidChangeCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "didClose": { + "description": "Whether the agent wants `document/didClose` events.", + "anyOf": [ + { + "$ref": "#/$defs/NesDocumentDidCloseCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "didSave": { + "description": "Whether the agent wants `document/didSave` events.", + "anyOf": [ + { + "$ref": "#/$defs/NesDocumentDidSaveCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "didFocus": { + "description": "Whether the agent wants `document/didFocus` events.", + "anyOf": [ + { + "$ref": "#/$defs/NesDocumentDidFocusCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "NesDocumentDidOpenCapabilities": { + "description": "Marker for `document/didOpen` capability support.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "NesDocumentDidChangeCapabilities": { + "description": "Capabilities for `document/didChange` events.", + "type": "object", + "properties": { + "syncKind": { + "description": "The sync kind the agent wants: `\"full\"` or `\"incremental\"`.", + "allOf": [ + { + "$ref": "#/$defs/TextDocumentSyncKind" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "syncKind" + ] + }, + "TextDocumentSyncKind": { + "description": "How the agent wants document changes delivered.", + "oneOf": [ + { + "description": "Client sends the entire file content on each change.", + "type": "string", + "const": "full" + }, + { + "description": "Client sends only the changed ranges.", + "type": "string", + "const": "incremental" + } + ] + }, + "NesDocumentDidCloseCapabilities": { + "description": "Marker for `document/didClose` capability support.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "NesDocumentDidSaveCapabilities": { + "description": "Marker for `document/didSave` capability support.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "NesDocumentDidFocusCapabilities": { + "description": "Marker for `document/didFocus` capability support.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "NesContextCapabilities": { + "description": "Context capabilities the agent wants attached to each suggestion request.", + "type": "object", + "properties": { + "recentFiles": { + "description": "Whether the agent wants recent files context.", + "anyOf": [ + { + "$ref": "#/$defs/NesRecentFilesCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "relatedSnippets": { + "description": "Whether the agent wants related snippets context.", + "anyOf": [ + { + "$ref": "#/$defs/NesRelatedSnippetsCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "editHistory": { + "description": "Whether the agent wants edit history context.", + "anyOf": [ + { + "$ref": "#/$defs/NesEditHistoryCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "userActions": { + "description": "Whether the agent wants user actions context.", + "anyOf": [ + { + "$ref": "#/$defs/NesUserActionsCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "openFiles": { + "description": "Whether the agent wants open files context.", + "anyOf": [ + { + "$ref": "#/$defs/NesOpenFilesCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "diagnostics": { + "description": "Whether the agent wants diagnostics context.", + "anyOf": [ + { + "$ref": "#/$defs/NesDiagnosticsCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "NesRecentFilesCapabilities": { + "description": "Capabilities for recent files context.", + "type": "object", + "properties": { + "maxCount": { + "description": "Maximum number of recent files the agent can use.", + "type": [ + "integer", + "null" + ], + "format": "uint32", + "minimum": 0, + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "NesRelatedSnippetsCapabilities": { + "description": "Capabilities for related snippets context.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "NesEditHistoryCapabilities": { + "description": "Capabilities for edit history context.", + "type": "object", + "properties": { + "maxCount": { + "description": "Maximum number of edit history entries the agent can use.", + "type": [ + "integer", + "null" + ], + "format": "uint32", + "minimum": 0, + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "NesUserActionsCapabilities": { + "description": "Capabilities for user actions context.", + "type": "object", + "properties": { + "maxCount": { + "description": "Maximum number of user actions the agent can use.", + "type": [ + "integer", + "null" + ], + "format": "uint32", + "minimum": 0, + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "NesOpenFilesCapabilities": { + "description": "Capabilities for open files context.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "NesDiagnosticsCapabilities": { + "description": "Capabilities for diagnostics context.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "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": [ + { + "description": "Character offsets count UTF-16 code units. This is the default.", + "type": "string", + "const": "utf-16" + }, + { + "description": "Character offsets count Unicode code points.", + "type": "string", + "const": "utf-32" + }, + { + "description": "Character offsets count UTF-8 code units (bytes).", + "type": "string", + "const": "utf-8" + } + ] + }, + "AuthMethod": { + "description": "Describes an available authentication method.\n\nThe `type` field acts as the discriminator in the serialized JSON form.", + "anyOf": [ + { + "description": "Client runs the configured agent program as a separate interactive\nprocess, without passing this method to `auth/login`.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "terminal" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/AuthMethodTerminal" + } + ] + }, + { + "description": "Agent handles authentication itself through `auth/login`.\n\nThe `type` discriminator value is `agent`.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "agent" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/AuthMethodAgent" + } + ] + }, + { + "title": "other", + "description": "Custom or future authentication method.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.\n\nClients that do not understand this method type should preserve the raw\npayload when storing, replaying, proxying, or forwarding initialization\ndata, and otherwise ignore the method or display it generically.", + "type": "object", + "properties": { + "type": { + "description": "Custom or future authentication method type.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + }, + "methodId": { + "description": "Unique identifier for this authentication method.", + "allOf": [ + { + "$ref": "#/$defs/AuthMethodId" + } + ] + }, + "name": { + "description": "Human-readable name of the authentication method.", + "type": "string" + }, + "description": { + "description": "Optional description providing more details about this authentication method.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "type", + "methodId", + "name" + ], + "not": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "agent" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "terminal" + } + }, + "required": [ + "type" + ] + } + ] + }, + "additionalProperties": true + } + ] + }, + "AuthMethodId": { + "description": "Typed identifier used for auth method values on the wire.", + "type": "string" + }, + "EnvVariable": { + "description": "An environment variable to set when launching a process.", + "type": "object", + "properties": { + "name": { + "description": "The name of the environment variable.", + "type": "string" + }, + "value": { + "description": "The value to set for the environment variable.", + "type": "string" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "name", + "value" + ] + }, + "AuthMethodTerminal": { + "description": "Terminal-based authentication method.\n\nThe client runs the configured agent program as a separate interactive\nprocess for the user to authenticate via a TUI. Agents MUST advertise this\nmethod only when the client enabled its terminal authentication capability.\nA zero exit status signals success; any other termination signals failure.\nThe client MUST NOT pass this method to `auth/login`.", + "type": "object", + "properties": { + "methodId": { + "description": "Unique identifier for this authentication method.", + "allOf": [ + { + "$ref": "#/$defs/AuthMethodId" + } + ] + }, + "name": { + "description": "Human-readable name of the authentication method.", + "type": "string" + }, + "description": { + "description": "Optional description providing more details about this authentication method.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "args": { + "description": "Additional arguments to append to the configured agent invocation for terminal auth.", + "type": "array", + "items": { + "type": "string" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "env": { + "description": "Additional environment variables to set on the configured agent invocation for terminal auth.\nNames MUST be unique. These values override same-named variables in the\nbase launch configuration.", + "type": "array", + "items": { + "$ref": "#/$defs/EnvVariable" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "methodId", + "name" + ] + }, + "AuthMethodAgent": { + "description": "Agent handles authentication itself through `auth/login`.\n\nThe `type` discriminator value is `agent`.", + "type": "object", + "properties": { + "methodId": { + "description": "Unique identifier for this authentication method.", + "allOf": [ + { + "$ref": "#/$defs/AuthMethodId" + } + ] + }, + "name": { + "description": "Human-readable name of the authentication method.", + "type": "string" + }, + "description": { + "description": "Optional description providing more details about this authentication method.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "methodId", + "name" + ] + }, + "LoginAuthResponse": { + "description": "Response to the `auth/login` method.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "x-side": "agent", + "x-method": "auth/login" + }, + "ListProvidersResponse": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse to `providers/list`.", + "type": "object", + "properties": { + "providers": { + "description": "Configurable providers with current routing info suitable for UI display.", + "type": "array", + "items": { + "$ref": "#/$defs/ProviderInfo" + } + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "providers" + ], + "x-side": "agent", + "x-method": "providers/list" + }, + "ProviderInfo": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInformation about a configurable LLM provider.", + "type": "object", + "properties": { + "providerId": { + "description": "Provider identifier, for example \"main\" or \"openai\".", + "allOf": [ + { + "$ref": "#/$defs/ProviderId" + } + ] + }, + "supported": { + "description": "Supported protocol types for this provider.", + "type": "array", + "items": { + "$ref": "#/$defs/LlmProtocol" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "required": { + "description": "Whether this provider is mandatory and cannot be disabled via `providers/disable`.\nIf true, clients must not call `providers/disable` for this provider ID.", + "type": "boolean" + }, + "current": { + "description": "Current effective non-secret routing config.\nNull or omitted means provider is disabled.", + "anyOf": [ + { + "$ref": "#/$defs/ProviderCurrentConfig" + }, + { + "type": "null" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "providerId", + "supported", + "required" + ] + }, + "ProviderId": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnique identifier for a configurable LLM provider.", + "type": "string" + }, + "LlmProtocol": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWell-known API protocol identifiers for LLM providers.\n\nAgents and clients MUST handle unknown protocol identifiers gracefully.\n\nProtocol names beginning with `_` are free for custom use, like other ACP extension methods.\nProtocol names that do not begin with `_` are reserved for the ACP spec.", + "anyOf": [ + { + "description": "Anthropic API protocol.", + "type": "string", + "const": "anthropic" + }, + { + "description": "OpenAI API protocol.", + "type": "string", + "const": "openai" + }, + { + "description": "Azure OpenAI API protocol.", + "type": "string", + "const": "azure" + }, + { + "description": "Google Vertex AI API protocol.", + "type": "string", + "const": "vertex" + }, + { + "description": "AWS Bedrock API protocol.", + "type": "string", + "const": "bedrock" + }, + { + "title": "other", + "description": "Custom or future protocol.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + ] + }, + "ProviderCurrentConfig": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCurrent effective non-secret routing configuration for a provider.", + "type": "object", + "properties": { + "apiType": { + "description": "Protocol currently used by this provider.", + "allOf": [ + { + "$ref": "#/$defs/LlmProtocol" + } + ] + }, + "baseUrl": { + "description": "Base URL currently used by this provider.", + "type": "string", + "format": "uri" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "apiType", + "baseUrl" + ] + }, + "SetProviderResponse": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse to `providers/set`.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "x-side": "agent", + "x-method": "providers/set" + }, + "DisableProviderResponse": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse to `providers/disable`.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "x-side": "agent", + "x-method": "providers/disable" + }, + "LogoutAuthResponse": { + "description": "Response to the `auth/logout` method.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "x-side": "agent", + "x-method": "auth/logout" + }, + "NewSessionResponse": { + "description": "Response from creating a new session.\n\nSee protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/v2/draft/session-setup#creating-a-session)", + "type": "object", + "properties": { + "sessionId": { + "description": "Unique identifier for the created session.\n\nUsed in all subsequent requests for this conversation.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "configOptions": { + "description": "Initial session configuration options.", + "type": "array", + "items": { + "$ref": "#/$defs/SessionConfigOption" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId" + ], + "x-side": "agent", + "x-method": "session/new" + }, + "SessionConfigOption": { + "description": "A session configuration option selector and its current state.", + "type": "object", + "properties": { + "configId": { + "description": "Unique identifier for the configuration option.", + "allOf": [ + { + "$ref": "#/$defs/SessionConfigId" + } + ] + }, + "name": { + "description": "Human-readable label for the option.", + "type": "string" + }, + "description": { + "description": "Optional description for the Client to display to the user.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "category": { + "description": "Optional semantic category for this option (UX only).", + "anyOf": [ + { + "$ref": "#/$defs/SessionConfigOptionCategory" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "configId", + "name" + ], + "anyOf": [ + { + "description": "Single-value selector (dropdown).", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "select" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/SessionConfigSelect" + } + ] + }, + { + "description": "Boolean on/off toggle.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "boolean" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/SessionConfigBoolean" + } + ] + }, + { + "title": "other", + "description": "Custom or future session configuration option payload.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.\n\nClients that do not understand this option type should preserve the raw\npayload when storing, replaying, proxying, or forwarding configuration\ndata, and otherwise ignore the option or display it generically.", + "type": "object", + "properties": { + "type": { + "description": "Custom or future session configuration option type.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + }, + "required": [ + "type" + ], + "not": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "select" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "boolean" + } + }, + "required": [ + "type" + ] + } + ] + }, + "additionalProperties": true + } + ] + }, + "SessionConfigId": { + "description": "Unique identifier for a session configuration option.", + "type": "string" + }, + "SessionConfigOptionCategory": { + "description": "Semantic category for a session configuration option.\n\nThis is intended to help Clients distinguish broadly common selectors (e.g. model selector vs\nsession mode selector vs thought/reasoning level) for UX purposes (keyboard shortcuts, icons,\nplacement). It MUST NOT be required for correctness. Clients MUST handle missing or unknown\ncategories gracefully.\n\nCategory names beginning with `_` are free for custom use, like other ACP extension methods.\nCategory names that do not begin with `_` are reserved for the ACP spec.", + "anyOf": [ + { + "description": "Session mode selector.", + "type": "string", + "const": "mode" + }, + { + "description": "Model selector.", + "type": "string", + "const": "model" + }, + { + "description": "Model-related configuration parameter.", + "type": "string", + "const": "model_config" + }, + { + "description": "Thought/reasoning level selector.", + "type": "string", + "const": "thought_level" + }, + { + "title": "other", + "description": "Custom or future category.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + ] + }, + "SessionConfigValueId": { + "description": "Unique identifier for a session configuration option value.", + "type": "string" + }, + "SessionConfigSelectOptions": { + "description": "Possible values for a session configuration option.", + "anyOf": [ + { + "title": "Ungrouped", + "description": "A flat list of options with no grouping.", + "type": "array", + "items": { + "$ref": "#/$defs/SessionConfigSelectOption" + } + }, + { + "title": "Grouped", + "description": "A list of options grouped under headers.", + "type": "array", + "items": { + "$ref": "#/$defs/SessionConfigSelectGroup" + } + } + ] + }, + "SessionConfigSelectOption": { + "description": "A possible value for a session configuration option.", + "type": "object", + "properties": { + "value": { + "description": "Unique identifier for this option value.", + "allOf": [ + { + "$ref": "#/$defs/SessionConfigValueId" + } + ] + }, + "name": { + "description": "Human-readable label for this option value.", + "type": "string" + }, + "description": { + "description": "Optional description for this option value.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "value", + "name" + ] + }, + "SessionConfigSelectGroup": { + "description": "A group of possible values for a session configuration option.", + "type": "object", + "properties": { + "groupId": { + "description": "Unique identifier for this group.", + "allOf": [ + { + "$ref": "#/$defs/SessionConfigGroupId" + } + ] + }, + "name": { + "description": "Human-readable label for this group.", + "type": "string" + }, + "options": { + "description": "The set of option values in this group.", + "type": "array", + "items": { + "$ref": "#/$defs/SessionConfigSelectOption" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "groupId", + "name", + "options" + ] + }, + "SessionConfigGroupId": { + "description": "Unique identifier for a session configuration option value group.", + "type": "string" + }, + "SessionConfigSelect": { + "description": "A single-value selector (dropdown) session configuration option payload.", + "type": "object", + "properties": { + "currentValue": { + "description": "The currently selected value.", + "allOf": [ + { + "$ref": "#/$defs/SessionConfigValueId" + } + ] + }, + "options": { + "description": "The set of selectable options.", + "allOf": [ + { + "$ref": "#/$defs/SessionConfigSelectOptions" + } + ] + } + }, + "required": [ + "currentValue", + "options" + ] + }, + "SessionConfigBoolean": { + "description": "A boolean on/off toggle session configuration option payload.", + "type": "object", + "properties": { + "currentValue": { + "description": "The current value of the boolean option.", + "type": "boolean" + } + }, + "required": [ + "currentValue" + ] + }, + "ListSessionsResponse": { + "description": "Response from listing sessions.", + "type": "object", + "properties": { + "sessions": { + "description": "Array of session information objects.", + "type": "array", + "items": { + "$ref": "#/$defs/SessionInfo" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "nextCursor": { + "description": "Opaque cursor token. If present, pass this in the next request's cursor parameter\nto fetch the next page. If absent, there are no more results.", + "anyOf": [ + { + "$ref": "#/$defs/SessionListCursor" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessions" + ], + "x-side": "agent", + "x-method": "session/list" + }, + "SessionInfo": { + "description": "Information about a session returned by session/list", + "type": "object", + "properties": { + "sessionId": { + "description": "Unique identifier for the session", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "cwd": { + "description": "The working directory for this session. Must be an absolute path.", + "allOf": [ + { + "$ref": "#/$defs/AbsolutePath" + } + ] + }, + "additionalDirectories": { + "description": "Additional workspace roots reported for this session. Each path must be absolute.\n\nWhen present, this is the complete ordered additional-root list reported\nby the Agent. Omitted and empty values are equivalent: the response\nreports no additional roots.", + "type": "array", + "items": { + "$ref": "#/$defs/AbsolutePath" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "title": { + "description": "Human-readable title for the session", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "updatedAt": { + "description": "RFC 3339 timestamp of last activity.", + "type": [ + "string", + "null" + ], + "format": "date-time", + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId", + "cwd" + ] + }, + "SessionListCursor": { + "description": "An opaque cursor used to paginate `session/list` results.", + "type": "string" + }, + "DeleteSessionResponse": { + "description": "Response from deleting a session.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "x-side": "agent", + "x-method": "session/delete" + }, + "ForkSessionResponse": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse from forking an existing session.", + "type": "object", + "properties": { + "sessionId": { + "description": "Unique identifier for the newly created forked session.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "configOptions": { + "description": "Initial session configuration options.", + "type": "array", + "items": { + "$ref": "#/$defs/SessionConfigOption" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId" + ], + "x-side": "agent", + "x-method": "session/fork" + }, + "ResumeSessionResponse": { + "description": "Response from resuming an existing session.", + "type": "object", + "properties": { + "configOptions": { + "description": "Initial session configuration options.", + "type": "array", + "items": { + "$ref": "#/$defs/SessionConfigOption" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "x-side": "agent", + "x-method": "session/resume" + }, + "CloseSessionResponse": { + "description": "Response from closing a session.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "x-side": "agent", + "x-method": "session/close" + }, + "SetSessionConfigOptionResponse": { + "description": "Response to `session/set_config_option` method.", + "type": "object", + "properties": { + "configOptions": { + "description": "The full set of configuration options and their current values.", + "type": "array", + "items": { + "$ref": "#/$defs/SessionConfigOption" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "configOptions" + ], + "x-side": "agent", + "x-method": "session/set_config_option" + }, + "PromptResponse": { + "description": "Response acknowledging that a user prompt was accepted.\n\nThis response does not indicate that the agent has finished processing.\nProcessing and completion are reported through `state_update` session updates.\n\nSee protocol docs: [Prompt Accepted](https://agentclientprotocol.com/protocol/v2/draft/prompt-lifecycle#2-prompt-accepted)", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "x-side": "agent", + "x-method": "session/prompt" + }, + "StartNesResponse": { + "description": "Response to `nes/start`.", + "type": "object", + "properties": { + "sessionId": { + "description": "The session ID for the newly started NES session.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId" + ], + "x-side": "agent", + "x-method": "nes/start" + }, + "SuggestNesResponse": { + "description": "Response to `nes/suggest`.", + "type": "object", + "properties": { + "suggestions": { + "description": "The list of suggestions.", + "type": "array", + "items": { + "$ref": "#/$defs/NesSuggestion" + } + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "suggestions" + ], + "x-side": "agent", + "x-method": "nes/suggest" + }, + "NesSuggestion": { + "description": "A suggestion returned by the agent.", + "anyOf": [ + { + "description": "A text edit suggestion.", + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "edit" + } + }, + "required": [ + "kind" + ], + "allOf": [ + { + "$ref": "#/$defs/NesEditSuggestion" + } + ] + }, + { + "description": "A jump-to-location suggestion.", + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "jump" + } + }, + "required": [ + "kind" + ], + "allOf": [ + { + "$ref": "#/$defs/NesJumpSuggestion" + } + ] + }, + { + "description": "A rename symbol suggestion.", + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "rename" + } + }, + "required": [ + "kind" + ], + "allOf": [ + { + "$ref": "#/$defs/NesRenameSuggestion" + } + ] + }, + { + "description": "A search-and-replace suggestion.", + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "searchAndReplace" + } + }, + "required": [ + "kind" + ], + "allOf": [ + { + "$ref": "#/$defs/NesSearchAndReplaceSuggestion" + } + ] + }, + { + "title": "other", + "description": "Custom or future NES suggestion.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.\n\nReceivers that do not understand this suggestion kind should preserve\nthe raw payload when storing, replaying, proxying, or forwarding\nsuggestions, and otherwise ignore it or display it generically.", + "type": "object", + "properties": { + "kind": { + "description": "Custom or future NES suggestion kind.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + }, + "suggestionId": { + "description": "Unique identifier for accept/reject tracking.", + "allOf": [ + { + "$ref": "#/$defs/NesSuggestionId" + } + ] + } + }, + "required": [ + "kind", + "suggestionId" + ], + "not": { + "anyOf": [ + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "edit" + } + }, + "required": [ + "kind" + ] + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "jump" + } + }, + "required": [ + "kind" + ] + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "rename" + } + }, + "required": [ + "kind" + ] + }, + { + "type": "object", + "properties": { + "kind": { + "type": "string", + "const": "searchAndReplace" + } + }, + "required": [ + "kind" + ] + } + ] + }, + "additionalProperties": true + } + ] + }, + "NesSuggestionId": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnique identifier for an NES suggestion.", + "type": "string" + }, + "NesTextEdit": { + "description": "A text edit within a suggestion.", + "type": "object", + "properties": { + "range": { + "description": "The range to replace.", + "allOf": [ + { + "$ref": "#/$defs/Range" + } + ] + }, + "newText": { + "description": "The replacement text.", + "type": "string" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "range", + "newText" + ] + }, + "Range": { + "description": "A range in a text document, expressed as start and end positions.", + "type": "object", + "properties": { + "start": { + "description": "The start position (inclusive).", + "allOf": [ + { + "$ref": "#/$defs/Position" + } + ] + }, + "end": { + "description": "The end position (exclusive).", + "allOf": [ + { + "$ref": "#/$defs/Position" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "start", + "end" + ] + }, + "Position": { + "description": "A zero-based position in a text document.\n\nThe meaning of `character` depends on the negotiated position encoding.", + "type": "object", + "properties": { + "line": { + "description": "Zero-based line number.", + "type": "integer", + "format": "uint32", + "minimum": 0 + }, + "character": { + "description": "Zero-based character offset (encoding-dependent).", + "type": "integer", + "format": "uint32", + "minimum": 0 + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "line", + "character" + ] + }, + "NesEditSuggestion": { + "description": "A text edit suggestion.", + "type": "object", + "properties": { + "suggestionId": { + "description": "Unique identifier for accept/reject tracking.", + "allOf": [ + { + "$ref": "#/$defs/NesSuggestionId" + } + ] + }, + "uri": { + "description": "The URI of the file to edit.", + "type": "string", + "format": "uri" + }, + "edits": { + "description": "The text edits to apply. Must contain at least one edit.", + "type": "array", + "items": { + "$ref": "#/$defs/NesTextEdit" + }, + "minItems": 1 + }, + "cursorPosition": { + "description": "Optional suggested cursor position after applying edits.", + "anyOf": [ + { + "$ref": "#/$defs/Position" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "suggestionId", + "uri", + "edits" + ] + }, + "NesJumpSuggestion": { + "description": "A jump-to-location suggestion.", + "type": "object", + "properties": { + "suggestionId": { + "description": "Unique identifier for accept/reject tracking.", + "allOf": [ + { + "$ref": "#/$defs/NesSuggestionId" + } + ] + }, + "uri": { + "description": "The file to navigate to.", + "type": "string", + "format": "uri" + }, + "position": { + "description": "The target position within the file.", + "allOf": [ + { + "$ref": "#/$defs/Position" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "suggestionId", + "uri", + "position" + ] + }, + "NesRenameSuggestion": { + "description": "A rename symbol suggestion.", + "type": "object", + "properties": { + "suggestionId": { + "description": "Unique identifier for accept/reject tracking.", + "allOf": [ + { + "$ref": "#/$defs/NesSuggestionId" + } + ] + }, + "uri": { + "description": "The file URI containing the symbol.", + "type": "string", + "format": "uri" + }, + "position": { + "description": "The position of the symbol to rename.", + "allOf": [ + { + "$ref": "#/$defs/Position" + } + ] + }, + "newName": { + "description": "The new name for the symbol.", + "type": "string" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "suggestionId", + "uri", + "position", + "newName" + ] + }, + "NesSearchAndReplaceSuggestion": { + "description": "A search-and-replace suggestion.", + "type": "object", + "properties": { + "suggestionId": { + "description": "Unique identifier for accept/reject tracking.", + "allOf": [ + { + "$ref": "#/$defs/NesSuggestionId" + } + ] + }, + "uri": { + "description": "The file URI to search within.", + "type": "string", + "format": "uri" + }, + "search": { + "description": "The text or pattern to find.", + "type": "string" + }, + "replace": { + "description": "The replacement text.", + "type": "string" + }, + "isRegex": { + "description": "Whether `search` is a regular expression. Defaults to `false`.", + "type": [ + "boolean", + "null" + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "suggestionId", + "uri", + "search", + "replace" + ] + }, + "CloseNesResponse": { + "description": "Response from closing an NES session.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "x-side": "agent", + "x-method": "nes/close" + }, + "ExtResponse": { + "description": "Allows for sending an arbitrary response to an [`ExtRequest`] that is not part of the ACP spec.\nExtension methods provide a way to add custom functionality while maintaining\nprotocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)" + }, + "MessageMcpResponse": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse to `mcp/message`.\n\nThis is the inner MCP response result payload. Any JSON value is valid.", + "x-side": "both", + "x-method": "mcp/message" + }, + "Error": { + "description": "JSON-RPC error object.\n\nRepresents an error that occurred during method execution, following the\nJSON-RPC 2.0 error object specification with optional additional data.\n\nSee protocol docs: [JSON-RPC Error Object](https://www.jsonrpc.org/specification#error_object)", + "type": "object", + "properties": { + "code": { + "description": "A number indicating the error type that occurred.\nThis must be an integer as defined in the JSON-RPC specification.", + "allOf": [ + { + "$ref": "#/$defs/ErrorCode" + } + ] + }, + "message": { + "description": "A string providing a short description of the error.\nThe message should be limited to a concise single sentence.", + "type": "string" + }, + "data": { + "description": "Optional primitive or structured value that contains additional information about the error.\nThis may include debugging information or context-specific details.", + "x-deserialize-default-on-error": true + } + }, + "required": [ + "code", + "message" + ] + }, + "ErrorCode": { + "description": "Predefined error codes for common JSON-RPC and ACP-specific errors.\n\nThese codes follow the JSON-RPC 2.0 specification for standard errors\nand use the reserved range (-32000 to -32099) for protocol-specific errors.", + "anyOf": [ + { + "title": "Parse error", + "description": "**Parse error**: Invalid JSON was received by the server.\nAn error occurred on the server while parsing the JSON text.", + "type": "integer", + "format": "int32", + "const": -32700 + }, + { + "title": "Invalid request", + "description": "**Invalid request**: The JSON sent is not a valid Request object.", + "type": "integer", + "format": "int32", + "const": -32600 + }, + { + "title": "Method not found", + "description": "**Method not found**: The method does not exist or is not available.", + "type": "integer", + "format": "int32", + "const": -32601 + }, + { + "title": "Invalid params", + "description": "**Invalid params**: Invalid method parameter(s).", + "type": "integer", + "format": "int32", + "const": -32602 + }, + { + "title": "Internal error", + "description": "**Internal error**: Internal JSON-RPC error.\nReserved for implementation-defined server errors.", + "type": "integer", + "format": "int32", + "const": -32603 + }, + { + "title": "Request cancelled", + "description": "**Request cancelled**: Execution of the method was aborted either due to a cancellation request from the caller or\nbecause of resource constraints or shutdown.", + "type": "integer", + "format": "int32", + "const": -32800 + }, + { + "title": "Authentication required", + "description": "**Authentication required**: Authentication is required before this operation can be performed.", + "type": "integer", + "format": "int32", + "const": -32000 + }, + { + "title": "Resource not found", + "description": "**Resource not found**: A given resource, such as a file, was not found.", + "type": "integer", + "format": "int32", + "const": -32002 + }, + { + "title": "Other", + "description": "Other undefined error code.", + "type": "integer", + "format": "int32" + } + ] + }, + "AgentNotification": { + "description": "A JSON-RPC notification object.", + "type": "object", + "properties": { + "method": { + "description": "The notification method name.", + "type": "string" + }, + "params": { + "description": "Method-specific notification parameters.", + "anyOf": [ + { + "description": "All possible notifications that an agent can send to a client.\n\nThis enum is used internally for routing RPC notifications. You typically won't need\nto use this directly.\n\nNotifications do not expect a response.", + "anyOf": [ + { + "title": "UpdateSessionNotification", + "description": "Handles session update notifications from the agent.\n\nThis is a notification endpoint (no response expected) that receives\nupdates about session activity, including message updates, message chunks,\ntool calls, and execution plans.\n\nNote: Clients SHOULD continue accepting tool call updates even after\nsending a `session/cancel` notification, as the agent may send final\nupdates before reporting an idle `state_update` with the cancelled\nstop reason.\n\nSee protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/v2/draft/prompt-lifecycle#3-agent-reports-output)", + "allOf": [ + { + "$ref": "#/$defs/UpdateSessionNotification" + } + ] + }, + { + "title": "CompleteElicitationNotification", + "description": "Notification that a URL-based elicitation has completed.\n\nSee protocol docs: [Elicitation](https://agentclientprotocol.com/protocol/v2/draft/elicitation#url-completion)", + "allOf": [ + { + "$ref": "#/$defs/CompleteElicitationNotification" + } + ] + }, + { + "title": "MessageMcpNotification", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nReceives an MCP-over-ACP notification.", + "allOf": [ + { + "$ref": "#/$defs/MessageMcpNotification" + } + ] + }, + { + "title": "ExtNotification", + "description": "Handles extension notifications from the agent.\n\nAllows the Agent to send an arbitrary notification that is not part of the ACP spec.\nExtension notifications provide a way to send one-way messages for custom functionality\nwhile maintaining protocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "allOf": [ + { + "$ref": "#/$defs/ExtNotification" + } + ] + } + ] + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "method" + ], + "x-docs-ignore": true + }, + "UpdateSessionNotification": { + "description": "Notification containing a session update from the agent.\n\nAgents can send session updates at any point while the session exists.\n\nSee protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/v2/draft/prompt-lifecycle#3-agent-reports-output)", + "type": "object", + "properties": { + "sessionId": { + "description": "The ID of the session this update pertains to.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "update": { + "description": "The actual update content.", + "allOf": [ + { + "$ref": "#/$defs/SessionUpdate" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId", + "update" + ], + "x-side": "client", + "x-method": "session/update" + }, + "SessionUpdate": { + "description": "Different types of updates that can be sent while a session exists.\n\nThese updates report messages, progress, and other session activity.\n\nSee protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/v2/draft/prompt-lifecycle#3-agent-reports-output)", + "anyOf": [ + { + "description": "A chunk of the user's message being streamed.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "user_message_chunk" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/ContentChunk" + } + ] + }, + { + "description": "A user message has been created or updated.\n\nAgents can send this when they accept or replay a user message. When a\nclient receives another `user_message` update with the same `messageId`,\nfields in the new update patch the previous fields for that message.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "user_message" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/UserMessage" + } + ] + }, + { + "description": "A chunk of the agent's response being streamed.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "agent_message_chunk" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/ContentChunk" + } + ] + }, + { + "description": "An agent message has been created or updated.\n\nAgents can send this in addition to streamed chunks. When a client\nreceives another `agent_message` update with the same `messageId`,\nfields in the new update patch the previous fields for that message.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "agent_message" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/AgentMessage" + } + ] + }, + { + "description": "A chunk of the agent's internal reasoning being streamed.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "agent_thought_chunk" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/ContentChunk" + } + ] + }, + { + "description": "An agent thought or reasoning message has been created or updated.\n\nAgents can send this in addition to streamed chunks. When a client\nreceives another `agent_thought` update with the same `messageId`,\nfields in the new update patch the previous fields for that message.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "agent_thought" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/AgentThought" + } + ] + }, + { + "description": "The state of the agent's foreground work has changed.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "state_update" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/StateUpdate" + } + ] + }, + { + "description": "A chunk of tool-call content being streamed.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "tool_call_content_chunk" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/ToolCallContentChunk" + } + ] + }, + { + "description": "A tool call has been created or updated.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "tool_call_update" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/ToolCallUpdate" + } + ] + }, + { + "description": "An agent-owned terminal has been created or updated.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "terminal_update" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/TerminalUpdate" + } + ] + }, + { + "description": "A chunk of bytes appended to an agent-owned terminal's output.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "terminal_output_chunk" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/TerminalOutputChunk" + } + ] + }, + { + "description": "A content update for a plan identified by ID.\nSee protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/v2/draft/agent-plan)", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "plan_update" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/PlanUpdate" + } + ] + }, + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRemoval notice for a plan identified by ID.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "plan_removed" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/PlanRemoved" + } + ] + }, + { + "description": "Available commands are ready or have changed", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "available_commands_update" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/AvailableCommandsUpdate" + } + ] + }, + { + "description": "Session configuration options have been updated.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "config_option_update" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/ConfigOptionUpdate" + } + ] + }, + { + "description": "Session metadata has been updated (title, timestamps, custom metadata)", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "session_info_update" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/SessionInfoUpdate" + } + ] + }, + { + "description": "Context window and cost update for the session.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "usage_update" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/UsageUpdate" + } + ] + }, + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA context compaction has been created or updated.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "compaction_update" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/CompactionUpdate" + } + ] + }, + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA content block appended to a context compaction's retained summary.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "compaction_summary_chunk" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/CompactionSummaryChunk" + } + ] + }, + { + "title": "other", + "description": "Custom or future session update.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.\n\nReceivers that do not understand this update type should preserve the\nraw payload when storing, replaying, proxying, or forwarding session\nhistory, and otherwise ignore it or display it generically.", + "type": "object", + "properties": { + "sessionUpdate": { + "description": "Custom or future session update type.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + }, + "required": [ + "sessionUpdate" + ], + "not": { + "anyOf": [ + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "user_message_chunk" + } + }, + "required": [ + "sessionUpdate" + ] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "user_message" + } + }, + "required": [ + "sessionUpdate" + ] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "agent_message_chunk" + } + }, + "required": [ + "sessionUpdate" + ] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "agent_message" + } + }, + "required": [ + "sessionUpdate" + ] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "agent_thought_chunk" + } + }, + "required": [ + "sessionUpdate" + ] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "agent_thought" + } + }, + "required": [ + "sessionUpdate" + ] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "state_update" + } + }, + "required": [ + "sessionUpdate" + ] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "tool_call_content_chunk" + } + }, + "required": [ + "sessionUpdate" + ] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "tool_call_update" + } + }, + "required": [ + "sessionUpdate" + ] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "terminal_update" + } + }, + "required": [ + "sessionUpdate" + ] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "terminal_output_chunk" + } + }, + "required": [ + "sessionUpdate" + ] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "plan_update" + } + }, + "required": [ + "sessionUpdate" + ] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "available_commands_update" + } + }, + "required": [ + "sessionUpdate" + ] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "config_option_update" + } + }, + "required": [ + "sessionUpdate" + ] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "session_info_update" + } + }, + "required": [ + "sessionUpdate" + ] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "plan_removed" + } + }, + "required": [ + "sessionUpdate" + ] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "usage_update" + } + }, + "required": [ + "sessionUpdate" + ] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "compaction_update" + } + }, + "required": [ + "sessionUpdate" + ] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "compaction_summary_chunk" + } + }, + "required": [ + "sessionUpdate" + ] + } + ] + }, + "additionalProperties": true + } + ] + }, + "MessageId": { + "description": "Unique identifier for a message within a session.", + "type": "string" + }, + "ContentChunk": { + "description": "A streamed item of message content.", + "type": "object", + "properties": { + "messageId": { + "description": "A unique identifier for the message this chunk belongs to.\n\nAll chunks belonging to the same message share the same `messageId`.\nA change in `messageId` indicates a new message has started.", + "allOf": [ + { + "$ref": "#/$defs/MessageId" + } + ] + }, + "content": { + "description": "A single item of content", + "allOf": [ + { + "$ref": "#/$defs/ContentBlock" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys. This field is chunk-scoped.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "messageId", + "content" + ] + }, + "UserMessage": { + "description": "A user message upsert.\n\nOnly [`UserMessage::message_id`] is required. `content` has patch semantics:\nan omitted field leaves existing message content unchanged, `null` clears the\nvalue, and a concrete array replaces the previous value. For a new\n`messageId`, omitted fields use client defaults. `content` is replaced as a\nwhole array; send `[]` or `null` to clear it.\n\nMessage updates and chunks are applied in the order they are received. When\na `user_message` update includes `content`, that array replaces any content\npreviously accumulated for the message, including content from earlier\nchunks. Later chunks with the same `messageId` append to the current\ncontent.", + "type": "object", + "properties": { + "messageId": { + "description": "A unique identifier for the message.", + "allOf": [ + { + "$ref": "#/$defs/MessageId" + } + ] + }, + "content": { + "description": "Complete replacement content for this message.", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/$defs/ContentBlock" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys. Omitted means no metadata update; `null` is an explicit clear signal.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "messageId" + ] + }, + "AgentMessage": { + "description": "An agent message upsert.\n\nOnly [`AgentMessage::message_id`] is required. `content` has patch semantics:\nan omitted field leaves existing message content unchanged, `null` clears the\nvalue, and a concrete array replaces the previous value. For a new\n`messageId`, omitted fields use client defaults. `content` is replaced as a\nwhole array; send `[]` or `null` to clear it.\n\nMessage updates and chunks are applied in the order they are received. When\nan `agent_message` update includes `content`, that array replaces any\ncontent previously accumulated for the message, including content from\nearlier chunks. Later chunks with the same `messageId` append to the current\ncontent.", + "type": "object", + "properties": { + "messageId": { + "description": "A unique identifier for the message.", + "allOf": [ + { + "$ref": "#/$defs/MessageId" + } + ] + }, + "content": { + "description": "Complete replacement content for this message.", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/$defs/ContentBlock" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys. Omitted means no metadata update; `null` is an explicit clear signal.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "messageId" + ] + }, + "AgentThought": { + "description": "An agent thought or reasoning message upsert.\n\nOnly [`AgentThought::message_id`] is required. `content` has patch semantics:\nan omitted field leaves existing thought content unchanged, `null` clears the\nvalue, and a concrete array replaces the previous value. For a new\n`messageId`, omitted fields use client defaults. `content` is replaced as a\nwhole array; send `[]` or `null` to clear it.\n\nMessage updates and chunks are applied in the order they are received. When\nan `agent_thought` update includes `content`, that array replaces any\ncontent previously accumulated for the thought, including content from\nearlier chunks. Later chunks with the same `messageId` append to the current\ncontent.", + "type": "object", + "properties": { + "messageId": { + "description": "A unique identifier for the thought message.", + "allOf": [ + { + "$ref": "#/$defs/MessageId" + } + ] + }, + "content": { + "description": "Complete replacement content for this thought message.", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/$defs/ContentBlock" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys. Omitted means no metadata update; `null` is an explicit clear signal.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "messageId" + ] + }, + "RunningStateUpdate": { + "description": "Foreground work is in progress.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "StopReason": { + "description": "Reasons why an agent stops active session work.\n\nSee protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/v2/draft/prompt-lifecycle#stop-reasons)", + "anyOf": [ + { + "description": "The active work ended successfully.", + "type": "string", + "const": "end_turn" + }, + { + "description": "The active work ended because the agent reached the maximum number of tokens.", + "type": "string", + "const": "max_tokens" + }, + { + "description": "The active work ended because the agent reached the maximum number of\nallowed agent requests before returning idle.", + "type": "string", + "const": "max_turn_requests" + }, + { + "description": "The active work ended because the agent refused to continue. The user\nprompt and everything that comes after it won't be included in the next\nprompt, so this should be reflected in the UI.", + "type": "string", + "const": "refusal" + }, + { + "description": "Active session work was cancelled by the client via `session/cancel`.\n\nAgents should report this stop reason on an idle `state_update` session update\nwhen cancellation succeeds, even if cancellation causes exceptions in\nunderlying operations.", + "type": "string", + "const": "cancelled" + }, + { + "title": "other", + "description": "Custom or future stop reason.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + ] + }, + "Usage": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nToken usage information for completed session work.", + "type": "object", + "properties": { + "totalTokens": { + "description": "Sum of all token types across session.", + "type": "integer", + "format": "uint64", + "minimum": 0 + }, + "inputTokens": { + "description": "Total input tokens.", + "type": "integer", + "format": "uint64", + "minimum": 0 + }, + "outputTokens": { + "description": "Total output tokens.", + "type": "integer", + "format": "uint64", + "minimum": 0 + }, + "thoughtTokens": { + "description": "Total thought/reasoning tokens", + "type": [ + "integer", + "null" + ], + "format": "uint64", + "minimum": 0, + "x-deserialize-default-on-error": true + }, + "cachedReadTokens": { + "description": "Total cache read tokens.", + "type": [ + "integer", + "null" + ], + "format": "uint64", + "minimum": 0, + "x-deserialize-default-on-error": true + }, + "cachedWriteTokens": { + "description": "Total cache write tokens.", + "type": [ + "integer", + "null" + ], + "format": "uint64", + "minimum": 0, + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "totalTokens", + "inputTokens", + "outputTokens" + ] + }, + "IdleStateUpdate": { + "description": "The agent is ready to process a new prompt.", + "type": "object", + "properties": { + "stopReason": { + "description": "Indicates why foreground work stopped.\n\nOptional. Omitted or `null` both mean the agent is not reporting a stop reason.\nAgents SHOULD include this when the idle transition ends foreground work.", + "anyOf": [ + { + "$ref": "#/$defs/StopReason" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "usage": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nToken usage for completed foreground work.\n\nOptional. Omitted or `null` both mean the agent is not reporting token\nusage for this state update.", + "anyOf": [ + { + "$ref": "#/$defs/Usage" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "RequiresActionStateUpdate": { + "description": "Foreground work is blocked on user action.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "StateUpdate": { + "description": "The state of the agent's foreground work has changed.\n\nBackground activity can continue and emit other `session/update` notifications\nwhile `idle`. Those notifications do not change this state.", + "anyOf": [ + { + "description": "Foreground work is in progress.", + "type": "object", + "properties": { + "state": { + "type": "string", + "const": "running" + } + }, + "required": [ + "state" + ], + "allOf": [ + { + "$ref": "#/$defs/RunningStateUpdate" + } + ] + }, + { + "description": "The agent is ready to process a new prompt.", + "type": "object", + "properties": { + "state": { + "type": "string", + "const": "idle" + } + }, + "required": [ + "state" + ], + "allOf": [ + { + "$ref": "#/$defs/IdleStateUpdate" + } + ] + }, + { + "description": "Foreground work is blocked on user action.", + "type": "object", + "properties": { + "state": { + "type": "string", + "const": "requires_action" + } + }, + "required": [ + "state" + ], + "allOf": [ + { + "$ref": "#/$defs/RequiresActionStateUpdate" + } + ] + }, + { + "title": "other", + "description": "Custom or future session state.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "object", + "properties": { + "state": { + "description": "Custom or future session state.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + }, + "required": [ + "state" + ], + "not": { + "anyOf": [ + { + "type": "object", + "properties": { + "state": { + "type": "string", + "const": "running" + } + }, + "required": [ + "state" + ] + }, + { + "type": "object", + "properties": { + "state": { + "type": "string", + "const": "idle" + } + }, + "required": [ + "state" + ] + }, + { + "type": "object", + "properties": { + "state": { + "type": "string", + "const": "requires_action" + } + }, + "required": [ + "state" + ] + } + ] + }, + "additionalProperties": true + } + ] + }, + "ToolCallContentChunk": { + "description": "A streamed item of tool-call content.\n\nTool-call content chunks append one [`ToolCallContent`] item to the current\ncontent for the matching [`ToolCallId`]. Agents can use\n[`ToolCallUpdate::content`] when they need to replace the whole content\ncollection instead.", + "type": "object", + "properties": { + "toolCallId": { + "description": "The ID of the tool call this content belongs to.", + "allOf": [ + { + "$ref": "#/$defs/ToolCallId" + } + ] + }, + "content": { + "description": "A single item of content produced by the tool call.", + "allOf": [ + { + "$ref": "#/$defs/ToolCallContent" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys. This field is chunk-scoped.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "toolCallId", + "content" + ] + }, + "TerminalOutput": { + "description": "An authoritative replacement snapshot of terminal output bytes.", + "type": "object", + "properties": { + "data": { + "description": "Base64-encoded replacement terminal output bytes.", + "type": "string", + "contentEncoding": "base64" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys. This metadata is scoped to the replacement snapshot. Omitted\nand `null` are equivalent and mean no snapshot metadata was provided.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "data" + ] + }, + "TerminalExitStatus": { + "description": "Exit information for an agent-owned terminal.\n\nThe presence of this object marks the terminal as exited, even when neither\nan exit code nor a signal is known.", + "type": "object", + "properties": { + "exitCode": { + "description": "Process exit code, when known. Omitted and `null` are equivalent.", + "type": [ + "integer", + "null" + ], + "format": "uint32", + "minimum": 0, + "x-deserialize-default-on-error": true + }, + "signal": { + "description": "Signal that terminated the process, when known.\n\nAgents should use the conventional platform signal name. POSIX examples\ninclude `SIGTERM`, `SIGKILL`, and `SIGINT`. Other platforms may use a\nplatform-specific name. Omitted and `null` are equivalent.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys. This metadata is scoped to the exit information. Omitted\nand `null` are equivalent and mean no exit metadata was provided.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "TerminalUpdate": { + "description": "An upsert for the stored state of an agent-owned terminal.\n\nOnly [`TerminalUpdate::terminal_id`] is required. Other fields have patch\nsemantics: omitted fields leave the stored value unchanged, `null` clears\nit, and concrete values replace it. When the terminal ID is new, omitted\nfields start unknown.", + "type": "object", + "properties": { + "terminalId": { + "description": "Unique identifier for this terminal within the session.", + "allOf": [ + { + "$ref": "#/$defs/TerminalId" + } + ] + }, + "command": { + "description": "The command being run.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "cwd": { + "description": "The absolute working directory of the command.", + "anyOf": [ + { + "$ref": "#/$defs/AbsolutePath" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "output": { + "description": "An authoritative replacement snapshot of terminal output bytes.", + "anyOf": [ + { + "$ref": "#/$defs/TerminalOutput" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "exitStatus": { + "description": "Exit information. A concrete object marks the terminal as exited.", + "anyOf": [ + { + "$ref": "#/$defs/TerminalExitStatus" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted means no metadata update; `null` is an\nexplicit clear signal. Implementations MUST NOT make assumptions about values at these keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "terminalId" + ] + }, + "TerminalOutputChunk": { + "description": "A chunk of bytes appended to an agent-owned terminal's output.", + "type": "object", + "properties": { + "terminalId": { + "description": "The terminal receiving these bytes.", + "allOf": [ + { + "$ref": "#/$defs/TerminalId" + } + ] + }, + "data": { + "description": "Independently base64-encoded terminal output bytes.", + "type": "string", + "contentEncoding": "base64" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys. This field is chunk-scoped. Omitted and `null` are\nequivalent and mean no chunk metadata was provided.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "terminalId", + "data" + ] + }, + "PlanUpdateContent": { + "description": "Updated content for a plan.", + "anyOf": [ + { + "description": "Structured plan entries.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "items" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/PlanItems" + } + ] + }, + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA URI pointing to a file containing the plan.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "file" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/PlanFile" + } + ] + }, + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRaw markdown content for the plan.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "markdown" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/PlanMarkdown" + } + ] + }, + { + "title": "other", + "description": "Custom or future plan update content.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.\n\nReceivers that do not understand this content type should preserve the\nraw payload when storing, replaying, proxying, or forwarding plans, and\notherwise ignore it or display it generically.", + "type": "object", + "properties": { + "type": { + "description": "Custom or future plan update content type.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + }, + "planId": { + "description": "The plan ID to update.", + "allOf": [ + { + "$ref": "#/$defs/PlanId" + } + ] + } + }, + "required": [ + "type", + "planId" + ], + "not": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "items" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "file" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "markdown" + } + }, + "required": [ + "type" + ] + } + ] + }, + "additionalProperties": true + } + ] + }, + "PlanId": { + "description": "Unique identifier for a plan within a session.", + "type": "string" + }, + "PlanEntry": { + "description": "A single entry in the execution plan.\n\nRepresents a task or goal that the assistant intends to accomplish\nas part of fulfilling the user's request.\nSee protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/v2/draft/agent-plan#plan-entries)", + "type": "object", + "properties": { + "content": { + "description": "Human-readable description of what this task aims to accomplish.", + "type": "string" + }, + "priority": { + "description": "The relative importance of this task.\nUsed to indicate which tasks are most critical to the overall goal.", + "allOf": [ + { + "$ref": "#/$defs/PlanEntryPriority" + } + ] + }, + "status": { + "description": "Current execution status of this task.", + "allOf": [ + { + "$ref": "#/$defs/PlanEntryStatus" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "content", + "priority", + "status" + ] + }, + "PlanEntryPriority": { + "description": "Priority levels for plan entries.\n\nUsed to indicate the relative importance or urgency of different\ntasks in the execution plan.\nSee protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/v2/draft/agent-plan#plan-entries)", + "anyOf": [ + { + "description": "High priority task - critical to the overall goal.", + "type": "string", + "const": "high" + }, + { + "description": "Medium priority task - important but not critical.", + "type": "string", + "const": "medium" + }, + { + "description": "Low priority task - nice to have but not essential.", + "type": "string", + "const": "low" + }, + { + "title": "other", + "description": "Custom or future plan entry priority.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + ] + }, + "PlanEntryStatus": { + "description": "Status of a plan entry in the execution flow.\n\nTracks the lifecycle of each task from planning through completion.\nSee protocol docs: [Plan Entries](https://agentclientprotocol.com/protocol/v2/draft/agent-plan#plan-entries)", + "anyOf": [ + { + "description": "The task has not started yet.", + "type": "string", + "const": "pending" + }, + { + "description": "The task is currently being worked on.", + "type": "string", + "const": "in_progress" + }, + { + "description": "The task has been successfully completed.", + "type": "string", + "const": "completed" + }, + { + "description": "The task was cancelled before it completed.", + "type": "string", + "const": "cancelled" + }, + { + "title": "other", + "description": "Custom or future plan entry status.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + ] + }, + "PlanItems": { + "description": "A plan represented as structured entries.", + "type": "object", + "properties": { + "planId": { + "description": "The plan ID to update.", + "allOf": [ + { + "$ref": "#/$defs/PlanId" + } + ] + }, + "entries": { + "description": "The list of tasks to be accomplished.\n\nWhen updating an item-based plan, the agent must send a complete list of all entries\nwith their current status. The client replaces that plan with each update.", + "type": "array", + "items": { + "$ref": "#/$defs/PlanEntry" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "planId", + "entries" + ] + }, + "PlanFile": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA plan represented by a file URI.", + "type": "object", + "properties": { + "planId": { + "description": "The plan ID to update.", + "allOf": [ + { + "$ref": "#/$defs/PlanId" + } + ] + }, + "uri": { + "description": "The URI of the file containing the plan.", + "type": "string", + "format": "uri" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "planId", + "uri" + ] + }, + "PlanMarkdown": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA plan represented as raw markdown content.", + "type": "object", + "properties": { + "planId": { + "description": "The plan ID to update.", + "allOf": [ + { + "$ref": "#/$defs/PlanId" + } + ] + }, + "content": { + "description": "Markdown content for the plan.", + "type": "string" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "planId", + "content" + ] + }, + "PlanUpdate": { + "description": "A content update for a plan identified by ID.", + "type": "object", + "properties": { + "plan": { + "description": "The updated plan content.", + "allOf": [ + { + "$ref": "#/$defs/PlanUpdateContent" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "plan" + ] + }, + "PlanRemoved": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRemoval notice for a plan identified by ID.", + "type": "object", + "properties": { + "planId": { + "description": "The plan ID to remove.", + "allOf": [ + { + "$ref": "#/$defs/PlanId" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "planId" + ] + }, + "AvailableCommand": { + "description": "Information about a command.", + "type": "object", + "properties": { + "name": { + "description": "Command name (e.g., `create_plan`, `research_codebase`).", + "type": "string" + }, + "description": { + "description": "Human-readable description of what the command does.", + "type": "string" + }, + "input": { + "description": "Input for the command if required", + "anyOf": [ + { + "$ref": "#/$defs/AvailableCommandInput" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "name", + "description" + ] + }, + "AvailableCommandInput": { + "description": "The input specification for a command.", + "anyOf": [ + { + "description": "All text that was typed after the command name is provided as input.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "text" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/TextCommandInput" + } + ] + }, + { + "title": "other", + "description": "Custom or future command input specification.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.\n\nClients that do not understand this input type should preserve the raw\npayload when storing, replaying, proxying, or forwarding command\nmetadata, and otherwise ignore the input specification or display the\ncommand without structured input.", + "type": "object", + "properties": { + "type": { + "description": "Custom or future command input type.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + }, + "required": [ + "type" + ], + "not": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "text" + } + }, + "required": [ + "type" + ] + } + ] + }, + "additionalProperties": true + } + ] + }, + "TextCommandInput": { + "description": "All text that was typed after the command name is provided as input.", + "type": "object", + "properties": { + "hint": { + "description": "A hint to display when the input hasn't been provided yet", + "type": "string" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "hint" + ] + }, + "AvailableCommandsUpdate": { + "description": "Available commands are ready or have changed", + "type": "object", + "properties": { + "availableCommands": { + "description": "Commands the agent can execute.", + "type": "array", + "items": { + "$ref": "#/$defs/AvailableCommand" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "availableCommands" + ] + }, + "ConfigOptionUpdate": { + "description": "Session configuration options have been updated.", + "type": "object", + "properties": { + "configOptions": { + "description": "The full set of configuration options and their current values.", + "type": "array", + "items": { + "$ref": "#/$defs/SessionConfigOption" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "configOptions" + ] + }, + "SessionInfoUpdate": { + "description": "Update to session metadata. All fields are optional to support partial updates.\n\nAgents send this notification to update session information like title or custom metadata.\nThis allows clients to display dynamic session names and track session state changes.\n\nOmitted fields leave the existing session info unchanged. `null` clears the\ncorresponding value.", + "type": "object", + "properties": { + "title": { + "description": "Human-readable title for the session. Set to null to clear.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "updatedAt": { + "description": "RFC 3339 timestamp of last activity. Set to null to clear.", + "type": [ + "string", + "null" + ], + "format": "date-time", + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted means no metadata update; `null` is an\nexplicit clear signal. Implementations MUST NOT make assumptions about values at these keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "Cost": { + "description": "Cost information for a session.", + "type": "object", + "properties": { + "amount": { + "description": "Total cumulative cost for session.", + "type": "number", + "format": "double" + }, + "currency": { + "description": "ISO 4217 currency code (e.g., \"USD\", \"EUR\").", + "type": "string", + "pattern": "^[A-Z]{3}$" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "amount", + "currency" + ] + }, + "UsageUpdate": { + "description": "Context window and cost update for a session.", + "type": "object", + "properties": { + "used": { + "description": "Tokens currently in context.", + "type": "integer", + "format": "uint64", + "minimum": 0 + }, + "size": { + "description": "Total context window size in tokens.", + "type": "integer", + "format": "uint64", + "minimum": 0 + }, + "cost": { + "description": "Cumulative session cost (optional).", + "anyOf": [ + { + "$ref": "#/$defs/Cost" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "used", + "size" + ] + }, + "CompactionId": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnique identifier for a context compaction within a session.", + "type": "string" + }, + "CompactionStatus": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nLifecycle state of a context compaction.", + "anyOf": [ + { + "description": "Compaction has started and has not finished.", + "type": "string", + "const": "in_progress" + }, + { + "description": "Compaction finished successfully.", + "type": "string", + "const": "completed" + }, + { + "description": "Compaction finished unsuccessfully.", + "type": "string", + "const": "failed" + }, + { + "description": "Compaction was cancelled before it finished.", + "type": "string", + "const": "cancelled" + }, + { + "title": "other", + "description": "Custom or future compaction status.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Other unknown values are reserved for future ACP statuses.", + "type": "string" + } + ] + }, + "CompactionUpdate": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA context compaction upsert. The first update fixes the compaction's\ntimeline position. Later updates with the same ID patch that entity in place.\n\n`summary`, `error`, and `_meta` have patch semantics: omission leaves the\nstored value unchanged, `null` clears it, and a concrete value replaces it.\n`summary: []` also clears the retained summary. A non-empty summary is only\nvalid with `completed`; `error` is only valid with `failed`.", + "type": "object", + "properties": { + "compactionId": { + "description": "The Agent-owned ID of this compaction, unique within the session.", + "allOf": [ + { + "$ref": "#/$defs/CompactionId" + } + ] + }, + "status": { + "description": "Current lifecycle status.", + "allOf": [ + { + "$ref": "#/$defs/CompactionStatus" + } + ] + }, + "summary": { + "description": "Complete replacement user-displayable summary retained by the compaction.", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/$defs/ContentBlock" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "error": { + "description": "Human-readable description of why the compaction failed.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "Extensible metadata patch for this compaction.", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "compactionId", + "status" + ] + }, + "CompactionSummaryChunk": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA content block appended to the retained summary of an in-progress\ncompaction. Agents send chunks only after an `in_progress` update and before\nthe terminal update for the same ID.", + "type": "object", + "properties": { + "compactionId": { + "description": "ID of the compaction whose summary receives this content.", + "allOf": [ + { + "$ref": "#/$defs/CompactionId" + } + ] + }, + "content": { + "description": "One content block to append.", + "allOf": [ + { + "$ref": "#/$defs/ContentBlock" + } + ] + }, + "_meta": { + "description": "Metadata scoped to this chunk. Omission and `null` both mean absent.", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "compactionId", + "content" + ] + }, + "CompleteElicitationNotification": { + "description": "Notification sent by the agent when a URL-based elicitation is complete.", + "type": "object", + "properties": { + "elicitationId": { + "description": "The ID of the elicitation that completed.", + "allOf": [ + { + "$ref": "#/$defs/ElicitationId" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "elicitationId" + ], + "x-side": "client", + "x-method": "elicitation/complete" + }, + "MessageMcpNotification": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nNotification parameters for `mcp/message`.\n\nThis is used when the wrapped MCP message is a notification and the outer JSON-RPC\nenvelope has no `id`.", + "type": "object", + "properties": { + "connectionId": { + "description": "The MCP-over-ACP connection this message is sent on.", + "allOf": [ + { + "$ref": "#/$defs/McpConnectionId" + } + ] + }, + "method": { + "description": "The inner MCP method name.", + "type": "string" + }, + "params": { + "description": "Optional inner MCP params.\n\nIf omitted or set to `null`, the inner MCP message has no params.", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "connectionId", + "method" + ], + "x-side": "both", + "x-method": "mcp/message" + }, + "ExtNotification": { + "description": "Allows the Agent to send an arbitrary notification that is not part of the ACP spec.\nExtension notifications provide a way to send one-way messages for custom functionality\nwhile maintaining protocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)" + }, + "ClientRequest": { + "description": "A JSON-RPC request object.", + "type": "object", + "properties": { + "id": { + "description": "The request id used to correlate the matching response.", + "allOf": [ + { + "$ref": "#/$defs/RequestId" + } + ] + }, + "method": { + "description": "The method name to invoke.", + "type": "string" + }, + "params": { + "description": "Method-specific request parameters.", + "anyOf": [ + { + "description": "All possible requests that a client can send to an agent.\n\nThis enum is used internally for routing RPC requests. You typically won't need\nto use this directly.\n\nThis enum encompasses all method calls from client to agent.", + "anyOf": [ + { + "title": "InitializeRequest", + "description": "Establishes the connection with a client and negotiates protocol capabilities.\n\nThis method is called once at the beginning of the connection to:\n- Negotiate the protocol version to use\n- Exchange capability information between client and agent\n- Determine available authentication methods\n\nThe agent should respond with its supported protocol version and capabilities.\n\nSee protocol docs: [Initialization](https://agentclientprotocol.com/protocol/v2/draft/initialization)", + "allOf": [ + { + "$ref": "#/$defs/InitializeRequest" + } + ] + }, + { + "title": "LoginAuthRequest", + "description": "Authenticates the client using the specified authentication method.\n\nAgents MUST support this method when their `initialize` response advertised\nat least one valid authentication method. Clients MUST call this method only\nwith a method whose type defines a protocol-driven login flow, and MUST NOT\ncall it when `authMethods` was omitted or empty.\n\nCalled when the agent requires authentication before allowing session creation.\nThe client provides the authentication method ID that was advertised during initialization.\n\nAfter successful authentication, the client can proceed to create sessions with\n`new_session` without receiving an `auth_required` error.\n\nSee protocol docs: [Initialization](https://agentclientprotocol.com/protocol/v2/draft/initialization)", + "allOf": [ + { + "$ref": "#/$defs/LoginAuthRequest" + } + ] + }, + { + "title": "ListProvidersRequest", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nLists providers that can be configured by the client.", + "allOf": [ + { + "$ref": "#/$defs/ListProvidersRequest" + } + ] + }, + { + "title": "SetProviderRequest", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nReplaces the configuration for a provider.", + "allOf": [ + { + "$ref": "#/$defs/SetProviderRequest" + } + ] + }, + { + "title": "DisableProviderRequest", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nDisables a provider.", + "allOf": [ + { + "$ref": "#/$defs/DisableProviderRequest" + } + ] + }, + { + "title": "LogoutAuthRequest", + "description": "Logs out of the current authenticated state.\n\nAgents MUST support this method when their `initialize` response advertised\nat least one valid authentication method. Clients MUST NOT call this method\nwhen `authMethods` was omitted or empty.\n\nAfter a successful logout, authentication-gated requests require the\nclient to complete an advertised authentication flow again. There is no\nguarantee about the behavior of already running sessions.", + "allOf": [ + { + "$ref": "#/$defs/LogoutAuthRequest" + } + ] + }, + { + "title": "NewSessionRequest", + "description": "Creates a new conversation session with the agent.\n\nSessions represent independent conversation contexts with their own history and state.\n\nThe agent should:\n- Create a new session context\n- Connect to any specified MCP servers\n- Return a unique session ID for future requests\n\nMay return an `auth_required` error if the agent requires authentication.\n\nSee protocol docs: [Session Setup](https://agentclientprotocol.com/protocol/v2/draft/session-setup)", + "allOf": [ + { + "$ref": "#/$defs/NewSessionRequest" + } + ] + }, + { + "title": "ListSessionsRequest", + "description": "Lists existing sessions known to the agent.\n\nThe agent should return metadata about sessions with optional filtering and pagination support.", + "allOf": [ + { + "$ref": "#/$defs/ListSessionsRequest" + } + ] + }, + { + "title": "DeleteSessionRequest", + "description": "Deletes an existing session from `session/list`.\n\nThis method is only available if the agent advertises the `session.delete` capability.", + "allOf": [ + { + "$ref": "#/$defs/DeleteSessionRequest" + } + ] + }, + { + "title": "ForkSessionRequest", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nForks an existing session to create a new independent session.\n\nThis method is only available if the agent advertises the `session.fork` capability.\n\nThe agent should create a new session with the same conversation context as the\noriginal, allowing operations like generating summaries without affecting the\noriginal session's history.", + "allOf": [ + { + "$ref": "#/$defs/ForkSessionRequest" + } + ] + }, + { + "title": "ResumeSessionRequest", + "description": "Resumes an existing session.\n\nThe agent should resume the session context, allowing the conversation\nto continue. If `replayFrom` is set, the agent should replay\nconversation history before responding.", + "allOf": [ + { + "$ref": "#/$defs/ResumeSessionRequest" + } + ] + }, + { + "title": "CloseSessionRequest", + "description": "Closes an active session and frees up any resources associated with it.\n\nThe agent must cancel any ongoing work (as if `session/cancel` was called)\nand then free up any resources associated with the session.", + "allOf": [ + { + "$ref": "#/$defs/CloseSessionRequest" + } + ] + }, + { + "title": "SetSessionConfigOptionRequest", + "description": "Sets the current value for a session configuration option.", + "allOf": [ + { + "$ref": "#/$defs/SetSessionConfigOptionRequest" + } + ] + }, + { + "title": "PromptRequest", + "description": "Processes a user prompt within a session.\n\nThis request accepts the prompt:\n- Receives user messages with optional context (files, images, etc.)\n- Returns once the prompt is accepted\n\nAfter acceptance, the Agent reports the accepted user message,\nprocessing state, output, tool calls, and completion through\n`session/update` notifications.\n\nSee protocol docs: [Prompt Lifecycle](https://agentclientprotocol.com/protocol/v2/draft/prompt-lifecycle)", + "allOf": [ + { + "$ref": "#/$defs/PromptRequest" + } + ] + }, + { + "title": "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.", + "allOf": [ + { + "$ref": "#/$defs/StartNesRequest" + } + ] + }, + { + "title": "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.", + "allOf": [ + { + "$ref": "#/$defs/SuggestNesRequest" + } + ] + }, + { + "title": "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.", + "allOf": [ + { + "$ref": "#/$defs/CloseNesRequest" + } + ] + }, + { + "title": "MessageMcpRequest", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nExchanges an MCP-over-ACP message.", + "allOf": [ + { + "$ref": "#/$defs/MessageMcpRequest" + } + ] + }, + { + "title": "ExtMethodRequest", + "description": "Handles extension method requests from the client.\n\nExtension methods provide a way to add custom functionality while maintaining\nprotocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "allOf": [ + { + "$ref": "#/$defs/ExtRequest" + } + ] + } + ] + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "id", + "method" + ], + "x-docs-ignore": true + }, + "InitializeRequest": { + "description": "Request parameters for the initialize method.\n\nSent by the client to establish connection and negotiate capabilities.\n\nSee protocol docs: [Initialization](https://agentclientprotocol.com/protocol/v2/draft/initialization)", + "type": "object", + "properties": { + "protocolVersion": { + "description": "The latest protocol version supported by the client.", + "allOf": [ + { + "$ref": "#/$defs/ProtocolVersion" + } + ] + }, + "info": { + "description": "Information about the implementation sending this initialize request.", + "allOf": [ + { + "$ref": "#/$defs/Implementation" + } + ] + }, + "capabilities": { + "description": "Capabilities supported by the client.", + "x-deserialize-default-on-error": true, + "default": {}, + "allOf": [ + { + "$ref": "#/$defs/ClientCapabilities" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "protocolVersion", + "info" + ], + "x-side": "agent", + "x-method": "initialize" + }, + "ClientCapabilities": { + "description": "Capabilities supported by the client.\n\nAdvertised during initialization to inform the agent about\navailable features and methods.\n\nSee protocol docs: [Client Capabilities](https://agentclientprotocol.com/protocol/v2/draft/initialization#client-capabilities)", + "type": "object", + "properties": { + "auth": { + "description": "Authentication capabilities supported by the client.\nDetermines which authentication method types the agent may include\nin its `InitializeResponse`.\n\nOptional. Omitted or `null` both mean the client does not advertise any\nauthentication-method extensions.", + "anyOf": [ + { + "$ref": "#/$defs/AuthCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "elicitation": { + "description": "Elicitation capabilities supported by the client.\nDetermines which elicitation modes the agent may use.\n\nOptional. Omitted or `null` both mean the client does not advertise\nelicitation support.", + "anyOf": [ + { + "$ref": "#/$defs/ElicitationCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "nes": { + "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.\n\nOptional. Omitted or `null` both mean the client does not advertise any\nNES suggestion-kind extensions.", + "anyOf": [ + { + "$ref": "#/$defs/ClientNesCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "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.", + "type": "array", + "items": { + "$ref": "#/$defs/PositionEncodingKind" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "AuthCapabilities": { + "description": "Authentication capabilities supported by the client.\n\nAdvertised during initialization to inform the agent which authentication\nmethod types the client can handle. This governs opt-in types that require\nadditional client-side support.", + "type": "object", + "properties": { + "terminal": { + "description": "Whether the client supports `terminal` authentication methods.\n\nOptional. Omitted or `null` both mean the client does not advertise support.\nThe client should supply `{}` only when it can reproduce the configured\nagent invocation in an interactive terminal. Supplying `{}` means the\nagent may include `terminal` entries in its authentication methods.", + "anyOf": [ + { + "$ref": "#/$defs/TerminalAuthCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "TerminalAuthCapabilities": { + "description": "Capabilities for terminal authentication methods.\n\nSupplying `{}` means the client can reproduce the configured agent\ninvocation in an interactive terminal and supports terminal authentication\nmethods.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "ElicitationCapabilities": { + "description": "Elicitation capabilities supported by the client.", + "type": "object", + "properties": { + "form": { + "description": "Whether the client supports form-based elicitation.\n\nOptional. Omitted and `null` are equivalent and mean form support is not advertised.\nSupplying `{}` explicitly advertises form support.", + "anyOf": [ + { + "$ref": "#/$defs/ElicitationFormCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "url": { + "description": "Whether the client supports URL-based elicitation.\n\nOptional. Omitted or `null` both mean the client does not advertise support.\nSupplying `{}` means the client supports URL-based elicitation.", + "anyOf": [ + { + "$ref": "#/$defs/ElicitationUrlCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "ElicitationFormCapabilities": { + "description": "Form-based elicitation capabilities.\n\nSupplying `{}` means the client supports form-based elicitation.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "ElicitationUrlCapabilities": { + "description": "URL-based elicitation capabilities.\n\nSupplying `{}` means the client supports URL-based elicitation.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "ClientNesCapabilities": { + "description": "NES capabilities advertised by the client during initialization.", + "type": "object", + "properties": { + "jump": { + "description": "Whether the client supports the `jump` suggestion kind.", + "anyOf": [ + { + "$ref": "#/$defs/NesJumpCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "rename": { + "description": "Whether the client supports the `rename` suggestion kind.", + "anyOf": [ + { + "$ref": "#/$defs/NesRenameCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "searchAndReplace": { + "description": "Whether the client supports the `searchAndReplace` suggestion kind.", + "anyOf": [ + { + "$ref": "#/$defs/NesSearchAndReplaceCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "NesJumpCapabilities": { + "description": "Marker for jump suggestion support.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "NesRenameCapabilities": { + "description": "Marker for rename suggestion support.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "NesSearchAndReplaceCapabilities": { + "description": "Marker for search and replace suggestion support.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "LoginAuthRequest": { + "description": "Request parameters for the `auth/login` method.\n\nSpecifies which authentication method to use.\n\nAgents MUST support this method when their `initialize` response advertised\nat least one valid authentication method. Clients MUST NOT call this method\nwhen `authMethods` was omitted or empty.", + "type": "object", + "properties": { + "methodId": { + "description": "The ID of the authentication method to use.\nMust be one of the methods advertised in the initialize response.", + "allOf": [ + { + "$ref": "#/$defs/AuthMethodId" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "methodId" + ], + "x-side": "agent", + "x-method": "auth/login" + }, + "ListProvidersRequest": { + "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 `providers/list`.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "x-side": "agent", + "x-method": "providers/list" + }, + "SetProviderRequest": { + "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 `providers/set`.\n\nReplaces the full configuration for one provider ID.", + "type": "object", + "properties": { + "providerId": { + "description": "Provider ID to configure.", + "allOf": [ + { + "$ref": "#/$defs/ProviderId" + } + ] + }, + "apiType": { + "description": "Protocol type for this provider.", + "allOf": [ + { + "$ref": "#/$defs/LlmProtocol" + } + ] + }, + "baseUrl": { + "description": "Base URL for requests sent through this provider.", + "type": "string", + "format": "uri" + }, + "headers": { + "description": "Full headers map for this provider.\nMay include authorization, routing, or other integration-specific headers.", + "type": "object", + "additionalProperties": { + "type": "string" + } + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "providerId", + "apiType", + "baseUrl" + ], + "x-side": "agent", + "x-method": "providers/set" + }, + "DisableProviderRequest": { + "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 `providers/disable`.", + "type": "object", + "properties": { + "providerId": { + "description": "Provider ID to disable.", + "allOf": [ + { + "$ref": "#/$defs/ProviderId" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "providerId" + ], + "x-side": "agent", + "x-method": "providers/disable" + }, + "LogoutAuthRequest": { + "description": "Request parameters for the `auth/logout` method.\n\nTerminates the current authenticated session.\n\nAgents MUST support this method when their `initialize` response advertised\nat least one valid authentication method. Clients MUST NOT call this method\nwhen `authMethods` was omitted or empty.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "x-side": "agent", + "x-method": "auth/logout" + }, + "NewSessionRequest": { + "description": "Request parameters for creating a new session.\n\nSee protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/v2/draft/session-setup#creating-a-session)", + "type": "object", + "properties": { + "cwd": { + "description": "The working directory for this session. Must be an absolute path.", + "allOf": [ + { + "$ref": "#/$defs/AbsolutePath" + } + ] + }, + "additionalDirectories": { + "description": "Additional workspace roots for this session. Each path must be absolute.\n\nThese expand the session's workspace scope without changing `cwd`, which\nremains the base for relative paths. When omitted or empty, no\nadditional roots are activated for the new session.", + "type": "array", + "items": { + "$ref": "#/$defs/AbsolutePath" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "mcpServers": { + "description": "List of MCP (Model Context Protocol) servers the agent should connect to.", + "type": "array", + "items": { + "$ref": "#/$defs/McpServer" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "cwd" + ], + "x-side": "agent", + "x-method": "session/new" + }, + "McpServer": { + "description": "Configuration for connecting to an MCP (Model Context Protocol) server.\n\nMCP servers provide tools and context that the agent can use when\nprocessing prompts.\n\nSee protocol docs: [MCP Servers](https://agentclientprotocol.com/protocol/v2/draft/session-setup#mcp-servers)", + "anyOf": [ + { + "description": "HTTP transport configuration\n\nOnly available when the Agent capabilities include `session.mcp.http`.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "http" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/McpServerHttp" + } + ] + }, + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nACP transport configuration\n\nOnly available when the Agent capabilities include `session.mcp.acp`.\nThe MCP server is provided by an ACP component and communicates over the ACP channel.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "acp" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/McpServerAcp" + } + ] + }, + { + "description": "Stdio transport configuration\n\nOnly available when the Agent capabilities include `session.mcp.stdio`.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "stdio" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/McpServerStdio" + } + ] + }, + { + "title": "other", + "description": "Custom or future MCP server transport configuration.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.\n\nReceivers that do not understand this transport should preserve the raw\npayload when storing, replaying, proxying, or forwarding session setup\ndata, and otherwise ignore it or reject the server configuration.", + "type": "object", + "properties": { + "type": { + "description": "Custom or future MCP server transport type.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + }, + "required": [ + "type" + ], + "not": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "http" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "stdio" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "acp" + } + }, + "required": [ + "type" + ] + } + ] + }, + "additionalProperties": true + } + ] + }, + "HttpHeader": { + "description": "An HTTP header to set when making requests to the MCP server.", + "type": "object", + "properties": { + "name": { + "description": "The name of the HTTP header.", + "type": "string" + }, + "value": { + "description": "The value to set for the HTTP header.", + "type": "string" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "name", + "value" + ] + }, + "McpServerHttp": { + "description": "HTTP transport configuration for MCP.", + "type": "object", + "properties": { + "name": { + "description": "Human-readable name identifying this MCP server.", + "type": "string" + }, + "url": { + "description": "URL to the MCP server.", + "type": "string", + "format": "uri" + }, + "headers": { + "description": "HTTP headers to set when making requests to the MCP server.", + "type": "array", + "items": { + "$ref": "#/$defs/HttpHeader" + } + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "name", + "url" + ] + }, + "McpServerAcp": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nACP transport configuration for MCP.\n\nThe MCP server is provided by an ACP component and communicates over the ACP channel\nusing `mcp/connect`, `mcp/message`, and `mcp/disconnect`.", + "type": "object", + "properties": { + "name": { + "description": "Human-readable name identifying this MCP server.", + "type": "string" + }, + "serverId": { + "description": "Unique identifier for this MCP server, generated by the component providing it.\n\nProviders MUST NOT reuse an ID for multiple ACP-transport MCP servers that are visible\non the same ACP connection.", + "allOf": [ + { + "$ref": "#/$defs/McpServerAcpId" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "name", + "serverId" + ] + }, + "McpServerStdio": { + "description": "Stdio transport configuration for MCP.", + "type": "object", + "properties": { + "name": { + "description": "Human-readable name identifying this MCP server.", + "type": "string" + }, + "command": { + "description": "Absolute path to the MCP server executable.", + "allOf": [ + { + "$ref": "#/$defs/AbsolutePath" + } + ] + }, + "args": { + "description": "Command-line arguments to pass to the MCP server.", + "type": "array", + "items": { + "type": "string" + } + }, + "env": { + "description": "Environment variables to set when launching the MCP server.", + "type": "array", + "items": { + "$ref": "#/$defs/EnvVariable" + } + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "name", + "command" + ] + }, + "ListSessionsRequest": { + "description": "Request parameters for listing existing sessions.", + "type": "object", + "properties": { + "cwd": { + "description": "Filter sessions by working directory. Must be an absolute path.", + "anyOf": [ + { + "$ref": "#/$defs/AbsolutePath" + }, + { + "type": "null" + } + ] + }, + "cursor": { + "description": "Opaque cursor token from a previous response's nextCursor field for cursor-based pagination", + "anyOf": [ + { + "$ref": "#/$defs/SessionListCursor" + }, + { + "type": "null" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "x-side": "agent", + "x-method": "session/list" + }, + "DeleteSessionRequest": { + "description": "Request parameters for deleting an existing session from `session/list`.\n\nOnly available if the Agent supports the `session.delete` capability.", + "type": "object", + "properties": { + "sessionId": { + "description": "The ID of the session to delete.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId" + ], + "x-side": "agent", + "x-method": "session/delete" + }, + "ForkSessionRequest": { + "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 forking an existing session.\n\nCreates a new session based on the context of an existing one, allowing\noperations like generating summaries without affecting the original session's history.\n\nOnly available if the Agent supports the `session.fork` capability.", + "type": "object", + "properties": { + "sessionId": { + "description": "The ID of the session to fork.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "cwd": { + "description": "The working directory for this session. Must be an absolute path.", + "allOf": [ + { + "$ref": "#/$defs/AbsolutePath" + } + ] + }, + "additionalDirectories": { + "description": "Additional workspace roots to activate for this session. Each path must be absolute.\n\nWhen omitted or empty, no additional roots are activated. When non-empty,\nthis is the complete resulting additional-root list for the forked\nsession.", + "type": "array", + "items": { + "$ref": "#/$defs/AbsolutePath" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "mcpServers": { + "description": "List of MCP servers to connect to for this session.", + "type": "array", + "items": { + "$ref": "#/$defs/McpServer" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId", + "cwd" + ], + "x-side": "agent", + "x-method": "session/fork" + }, + "ResumeSessionRequest": { + "description": "Request parameters for resuming an existing session.\n\nResumes an existing session and optionally replays prior conversation\nhistory according to `replayFrom`.", + "type": "object", + "properties": { + "sessionId": { + "description": "The ID of the session to resume.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "cwd": { + "description": "The working directory for this session. Must be an absolute path.", + "allOf": [ + { + "$ref": "#/$defs/AbsolutePath" + } + ] + }, + "additionalDirectories": { + "description": "Additional workspace roots to activate for this session. Each path must be absolute.\n\nWhen omitted or empty, no additional roots are activated. When non-empty,\nthis is the complete resulting additional-root list for the resumed\nsession. It may differ from any previously used or reported list as long as\nthe request `cwd` matches the session's `cwd`.", + "type": "array", + "items": { + "$ref": "#/$defs/AbsolutePath" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "mcpServers": { + "description": "List of MCP servers to connect to for this session.", + "type": "array", + "items": { + "$ref": "#/$defs/McpServer" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "replayFrom": { + "description": "Inclusive cursor describing where conversation replay should begin.\n\nOptional. Omitted or `null` both mean the Agent should resume without\nreplaying previous conversation history. Replay cursors are inclusive:\nreplay includes the position identified by the cursor. Supplying\n`{ \"type\": \"start\" }` means the Agent should replay the whole\nconversation before responding.", + "anyOf": [ + { + "$ref": "#/$defs/ReplayFrom" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId", + "cwd" + ], + "x-side": "agent", + "x-method": "session/resume" + }, + "ReplayFrom": { + "description": "Inclusive cursor describing where replayed session history should begin.\n\nReplay includes the position identified by the cursor.", + "anyOf": [ + { + "description": "Replay the whole conversation from its first replayable entry.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "start" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/ReplayFromStart" + } + ] + }, + { + "title": "other", + "description": "Custom or future replay cursor.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.\n\nReceivers that do not understand this cursor should preserve the raw\npayload when storing, replaying, proxying, or forwarding requests, and\notherwise reject the request rather than guessing where to replay from.", + "type": "object", + "properties": { + "type": { + "description": "Custom or future replay cursor type.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "type" + ], + "not": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "start" + } + }, + "required": [ + "type" + ] + } + ] + }, + "additionalProperties": true + } + ] + }, + "ReplayFromStart": { + "description": "Inclusive replay cursor requesting replay from the start of the conversation.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "CloseSessionRequest": { + "description": "Request parameters for closing an active session.\n\nThe agent **must** cancel any ongoing work related to the session (treat it\nas if `session/cancel` was called) and then free up any resources associated\nwith the session.", + "type": "object", + "properties": { + "sessionId": { + "description": "The ID of the session to close.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId" + ], + "x-side": "agent", + "x-method": "session/close" + }, + "SetSessionConfigOptionRequest": { + "description": "Request parameters for setting a session configuration option.", + "type": "object", + "properties": { + "sessionId": { + "description": "The ID of the session to set the configuration option for.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "configId": { + "description": "The ID of the configuration option to set.", + "allOf": [ + { + "$ref": "#/$defs/SessionConfigId" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId", + "configId" + ], + "anyOf": [ + { + "description": "A [`SessionConfigValueId`] string value (`type: \"id\"`).", + "type": "object", + "properties": { + "value": { + "description": "The value ID.", + "allOf": [ + { + "$ref": "#/$defs/SessionConfigValueId" + } + ] + }, + "type": { + "type": "string", + "const": "id" + } + }, + "required": [ + "type", + "value" + ] + }, + { + "description": "A boolean value (`type: \"boolean\"`).", + "type": "object", + "properties": { + "value": { + "description": "The boolean value.", + "type": "boolean" + }, + "type": { + "type": "string", + "const": "boolean" + } + }, + "required": [ + "type", + "value" + ] + }, + { + "title": "other", + "description": "Custom or future session configuration option value payload.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "object", + "properties": { + "type": { + "description": "Custom or future session configuration option value type.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + }, + "value": { + "description": "Raw value payload for the custom or future value type." + } + }, + "required": [ + "type", + "value" + ], + "not": { + "anyOf": [ + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "id" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "boolean" + } + }, + "required": [ + "type" + ] + } + ] + }, + "additionalProperties": true + } + ], + "x-side": "agent", + "x-method": "session/set_config_option" + }, + "PromptRequest": { + "description": "Request parameters for sending a user prompt to the agent.\n\nContains the user's message and any additional context.\n\nSee protocol docs: [User Message](https://agentclientprotocol.com/protocol/v2/draft/prompt-lifecycle#1-user-message)", + "type": "object", + "properties": { + "sessionId": { + "description": "The ID of the session to send this user message to", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "prompt": { + "description": "The blocks of content that compose the user's message.\n\nAs a baseline, the Agent MUST support [`ContentBlock::Text`] and [`ContentBlock::ResourceLink`],\nwhile other variants are optionally enabled via [`PromptCapabilities`].\n\nThe Client MUST adapt its interface according to [`PromptCapabilities`].\n\nThe client MAY include referenced pieces of context as either\n[`ContentBlock::Resource`] or [`ContentBlock::ResourceLink`].\n\nWhen available, [`ContentBlock::Resource`] is preferred\nas it avoids extra round-trips and allows the message to include\npieces of context from sources the agent may not have access to.", + "type": "array", + "items": { + "$ref": "#/$defs/ContentBlock" + } + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId", + "prompt" + ], + "x-side": "agent", + "x-method": "session/prompt" + }, + "StartNesRequest": { + "description": "Request to start an NES session.", + "type": "object", + "properties": { + "workspaceUri": { + "description": "The root URI of the workspace.", + "type": [ + "string", + "null" + ], + "format": "uri", + "x-deserialize-default-on-error": true + }, + "workspaceFolders": { + "description": "The workspace folders.", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/$defs/WorkspaceFolder" + } + }, + "repository": { + "description": "Repository metadata, if the workspace is a git repository.", + "anyOf": [ + { + "$ref": "#/$defs/NesRepository" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "x-side": "agent", + "x-method": "nes/start" + }, + "WorkspaceFolder": { + "description": "A workspace folder.", + "type": "object", + "properties": { + "uri": { + "description": "The URI of the folder.", + "type": "string", + "format": "uri" + }, + "name": { + "description": "The display name of the folder.", + "type": "string" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "uri", + "name" + ] + }, + "NesRepository": { + "description": "Repository metadata for an NES session.", + "type": "object", + "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" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "name", + "owner", + "remoteUrl" + ] + }, + "SuggestNesRequest": { + "description": "Request for a code suggestion.", + "type": "object", + "properties": { + "sessionId": { + "description": "The session ID for this request.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "uri": { + "description": "The URI of the document to suggest for.", + "type": "string", + "format": "uri" + }, + "version": { + "description": "The version number of the document.", + "type": "integer", + "format": "int64" + }, + "position": { + "description": "The current cursor position.", + "allOf": [ + { + "$ref": "#/$defs/Position" + } + ] + }, + "selection": { + "description": "The current text selection range, if any.", + "anyOf": [ + { + "$ref": "#/$defs/Range" + }, + { + "type": "null" + } + ] + }, + "triggerKind": { + "description": "What triggered this suggestion request.", + "allOf": [ + { + "$ref": "#/$defs/NesTriggerKind" + } + ] + }, + "context": { + "description": "Context for the suggestion, included based on agent capabilities.", + "anyOf": [ + { + "$ref": "#/$defs/NesSuggestContext" + }, + { + "type": "null" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId", + "uri", + "version", + "position", + "triggerKind" + ], + "x-side": "agent", + "x-method": "nes/suggest" + }, + "NesTriggerKind": { + "description": "What triggered the suggestion request.", + "anyOf": [ + { + "description": "Triggered by user typing or cursor movement.", + "type": "string", + "const": "automatic" + }, + { + "description": "Triggered by a diagnostic appearing at or near the cursor.", + "type": "string", + "const": "diagnostic" + }, + { + "description": "Triggered by an explicit user action (keyboard shortcut).", + "type": "string", + "const": "manual" + }, + { + "title": "Other", + "description": "Custom or future suggestion trigger kind.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + ] + }, + "NesSuggestContext": { + "description": "Context attached to a suggestion request.", + "type": "object", + "properties": { + "recentFiles": { + "description": "Recently accessed files.", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/$defs/NesRecentFile" + } + }, + "relatedSnippets": { + "description": "Related code snippets.", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/$defs/NesRelatedSnippet" + } + }, + "editHistory": { + "description": "Recent edit history.", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/$defs/NesEditHistoryEntry" + } + }, + "userActions": { + "description": "Recent user actions (typing, navigation, etc.).", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/$defs/NesUserAction" + } + }, + "openFiles": { + "description": "Currently open files in the editor.", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/$defs/NesOpenFile" + } + }, + "diagnostics": { + "description": "Current diagnostics (errors, warnings).", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/$defs/NesDiagnostic" + } + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "NesRecentFile": { + "description": "A recently accessed file.", + "type": "object", + "properties": { + "uri": { + "description": "The URI of the file.", + "type": "string", + "format": "uri" + }, + "languageId": { + "description": "The language identifier.", + "type": "string" + }, + "text": { + "description": "The full text content of the file.", + "type": "string" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "uri", + "languageId", + "text" + ] + }, + "NesRelatedSnippet": { + "description": "A related code snippet from a file.", + "type": "object", + "properties": { + "uri": { + "description": "The URI of the file containing the snippets.", + "type": "string", + "format": "uri" + }, + "excerpts": { + "description": "The code excerpts.", + "type": "array", + "items": { + "$ref": "#/$defs/NesExcerpt" + } + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "uri", + "excerpts" + ] + }, + "NesExcerpt": { + "description": "A code excerpt from a file.", + "type": "object", + "properties": { + "startLine": { + "description": "The start line of the excerpt (zero-based).", + "type": "integer", + "format": "uint32", + "minimum": 0 + }, + "endLine": { + "description": "The end line of the excerpt (zero-based).", + "type": "integer", + "format": "uint32", + "minimum": 0 + }, + "text": { + "description": "The text content of the excerpt.", + "type": "string" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "startLine", + "endLine", + "text" + ] + }, + "NesEditHistoryEntry": { + "description": "An entry in the edit history.", + "type": "object", + "properties": { + "uri": { + "description": "The URI of the edited file.", + "type": "string", + "format": "uri" + }, + "diff": { + "description": "A diff representing the edit.", + "type": "string" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "uri", + "diff" + ] + }, + "NesUserAction": { + "description": "A user action (typing, cursor movement, etc.).", + "type": "object", + "properties": { + "action": { + "description": "The kind of action (e.g., \"insertChar\", \"cursorMovement\").", + "type": "string" + }, + "uri": { + "description": "The URI of the file where the action occurred.", + "type": "string", + "format": "uri" + }, + "position": { + "description": "The position where the action occurred.", + "allOf": [ + { + "$ref": "#/$defs/Position" + } + ] + }, + "timestampMs": { + "description": "Timestamp in milliseconds since epoch.", + "type": "integer", + "format": "uint64", + "minimum": 0 + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "action", + "uri", + "position", + "timestampMs" + ] + }, + "NesOpenFile": { + "description": "An open file in the editor.", + "type": "object", + "properties": { + "uri": { + "description": "The URI of the file.", + "type": "string", + "format": "uri" + }, + "languageId": { + "description": "The language identifier.", + "type": "string" + }, + "visibleRange": { + "description": "The visible range in the editor, if any.", + "anyOf": [ + { + "$ref": "#/$defs/Range" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "lastFocusedMs": { + "description": "Timestamp in milliseconds since epoch of when the file was last focused.", + "type": [ + "integer", + "null" + ], + "format": "uint64", + "minimum": 0, + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "uri", + "languageId" + ] + }, + "NesDiagnostic": { + "description": "A diagnostic (error, warning, etc.).", + "type": "object", + "properties": { + "uri": { + "description": "The URI of the file containing the diagnostic.", + "type": "string", + "format": "uri" + }, + "range": { + "description": "The range of the diagnostic.", + "allOf": [ + { + "$ref": "#/$defs/Range" + } + ] + }, + "severity": { + "description": "The severity of the diagnostic.", + "allOf": [ + { + "$ref": "#/$defs/NesDiagnosticSeverity" + } + ] + }, + "message": { + "description": "The diagnostic message.", + "type": "string" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "uri", + "range", + "severity", + "message" + ] + }, + "NesDiagnosticSeverity": { + "description": "Severity of a diagnostic.", + "anyOf": [ + { + "description": "An error.", + "type": "string", + "const": "error" + }, + { + "description": "A warning.", + "type": "string", + "const": "warning" + }, + { + "description": "An informational message.", + "type": "string", + "const": "information" + }, + { + "description": "A hint.", + "type": "string", + "const": "hint" + }, + { + "title": "Other", + "description": "Custom or future diagnostic severity.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + ] + }, + "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.", + "type": "object", + "properties": { + "sessionId": { + "description": "The ID of the NES session to close.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId" + ], + "x-side": "agent", + "x-method": "nes/close" + }, + "ClientResponse": { + "description": "A JSON-RPC response object.", + "anyOf": [ + { + "title": "Result", + "description": "A successful JSON-RPC response.", + "type": "object", + "properties": { + "id": { + "description": "The id of the request this response answers.", + "allOf": [ + { + "$ref": "#/$defs/RequestId" + } + ] + }, + "result": { + "description": "Method-specific response data.", + "anyOf": [ + { + "title": "RequestPermissionResponse", + "description": "Successful result returned for a `session/request_permission` request.", + "allOf": [ + { + "$ref": "#/$defs/RequestPermissionResponse" + } + ] + }, + { + "title": "CreateElicitationResponse", + "description": "Successful result returned for a `elicitation/create` request.", + "allOf": [ + { + "$ref": "#/$defs/CreateElicitationResponse" + } + ] + }, + { + "title": "ConnectMcpResponse", + "description": "Successful result returned for a `mcp/connect` request.", + "allOf": [ + { + "$ref": "#/$defs/ConnectMcpResponse" + } + ] + }, + { + "title": "DisconnectMcpResponse", + "description": "Successful result returned for a `mcp/disconnect` request.", + "allOf": [ + { + "$ref": "#/$defs/DisconnectMcpResponse" + } + ] + }, + { + "title": "MessageMcpResponse", + "description": "Successful result returned by an MCP-over-ACP `mcp/message` request.", + "allOf": [ + { + "$ref": "#/$defs/MessageMcpResponse" + } + ] + }, + { + "title": "ExtMethodResponse", + "description": "Successful result returned by an extension method outside the core ACP method set.", + "allOf": [ + { + "$ref": "#/$defs/ExtResponse" + } + ] + } + ] + } + }, + "required": [ + "id", + "result" + ] + }, + { + "title": "Error", + "description": "A failed JSON-RPC response.", + "type": "object", + "properties": { + "id": { + "description": "The id of the request this response answers.", + "allOf": [ + { + "$ref": "#/$defs/RequestId" + } + ] + }, + "error": { + "description": "Method-specific error data.", + "allOf": [ + { + "$ref": "#/$defs/Error" + } + ] + } + }, + "required": [ + "id", + "error" + ] + } + ], + "x-docs-ignore": true + }, + "RequestPermissionResponse": { + "description": "Response to a permission request.", + "type": "object", + "properties": { + "outcome": { + "description": "The user's decision on the permission request.", + "allOf": [ + { + "$ref": "#/$defs/RequestPermissionOutcome" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "outcome" + ], + "x-side": "client", + "x-method": "session/request_permission" + }, + "RequestPermissionOutcome": { + "description": "The outcome of a permission request.", + "anyOf": [ + { + "description": "Active session work was cancelled before the user responded.\n\nWhen a client sends a `session/cancel` notification to cancel active\nsession work, it MUST respond to all pending `session/request_permission`\nrequests with this `Cancelled` outcome.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/draft/prompt-lifecycle#cancellation)", + "type": "object", + "properties": { + "outcome": { + "type": "string", + "const": "cancelled" + } + }, + "required": [ + "outcome" + ] + }, + { + "description": "The user selected one of the provided options.", + "type": "object", + "properties": { + "outcome": { + "type": "string", + "const": "selected" + } + }, + "required": [ + "outcome" + ], + "allOf": [ + { + "$ref": "#/$defs/SelectedPermissionOutcome" + } + ] + }, + { + "title": "other", + "description": "Custom or future permission outcome.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.\n\nAgents that do not understand this outcome MUST NOT treat it as approval.\nThey should preserve the raw payload when storing, replaying, proxying, or\nforwarding permission responses, and otherwise fail or decline the\npermission request according to policy.", + "type": "object", + "properties": { + "outcome": { + "description": "Custom or future permission outcome.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + }, + "required": [ + "outcome" + ], + "not": { + "anyOf": [ + { + "type": "object", + "properties": { + "outcome": { + "type": "string", + "const": "cancelled" + } + }, + "required": [ + "outcome" + ] + }, + { + "type": "object", + "properties": { + "outcome": { + "type": "string", + "const": "selected" + } + }, + "required": [ + "outcome" + ] + } + ] + }, + "additionalProperties": true + } + ] + }, + "SelectedPermissionOutcome": { + "description": "The user selected one of the provided options.", + "type": "object", + "properties": { + "optionId": { + "description": "The ID of the option the user selected.", + "allOf": [ + { + "$ref": "#/$defs/PermissionOptionId" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "optionId" + ] + }, + "CreateElicitationResponse": { + "description": "Response from the client to an elicitation request.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "anyOf": [ + { + "description": "The user accepted and provided content.", + "type": "object", + "properties": { + "action": { + "type": "string", + "const": "accept" + } + }, + "required": [ + "action" + ], + "allOf": [ + { + "$ref": "#/$defs/ElicitationAcceptAction" + } + ] + }, + { + "description": "The user declined the elicitation.", + "type": "object", + "properties": { + "action": { + "type": "string", + "const": "decline" + } + }, + "required": [ + "action" + ] + }, + { + "description": "The elicitation was cancelled.", + "type": "object", + "properties": { + "action": { + "type": "string", + "const": "cancel" + } + }, + "required": [ + "action" + ] + }, + { + "title": "other", + "description": "Custom or future elicitation action.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.\n\nAgents that do not understand this action should preserve the raw\npayload when storing, replaying, proxying, or forwarding elicitation\nresponses. They MUST NOT treat it as a known elicitation action.", + "type": "object", + "properties": { + "action": { + "description": "Custom or future elicitation action.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + }, + "required": [ + "action" + ], + "not": { + "anyOf": [ + { + "type": "object", + "properties": { + "action": { + "type": "string", + "const": "accept" + } + }, + "required": [ + "action" + ] + }, + { + "type": "object", + "properties": { + "action": { + "type": "string", + "const": "decline" + } + }, + "required": [ + "action" + ] + }, + { + "type": "object", + "properties": { + "action": { + "type": "string", + "const": "cancel" + } + }, + "required": [ + "action" + ] + } + ] + }, + "additionalProperties": true + } + ], + "x-side": "client", + "x-method": "elicitation/create" + }, + "ElicitationContentValue": { + "description": "Allowed wire representations for [`ElicitationContentValue`].", + "anyOf": [ + { + "title": "String", + "description": "String value accepted in elicitation response content.", + "type": "string" + }, + { + "title": "Integer", + "description": "Integer value accepted in elicitation response content.", + "type": "integer", + "format": "int64" + }, + { + "title": "Number", + "description": "Number value accepted in elicitation response content.", + "type": "number", + "format": "double" + }, + { + "title": "Boolean", + "description": "Boolean value accepted in elicitation response content.", + "type": "boolean" + }, + { + "title": "StringArray", + "description": "String array value accepted in elicitation response content.", + "type": "array", + "items": { + "type": "string" + } + } + ] + }, + "ElicitationAcceptAction": { + "description": "The user accepted the elicitation and provided content.", + "type": "object", + "properties": { + "content": { + "description": "The user-provided content, if any, as an object matching the requested schema.", + "type": [ + "object", + "null" + ], + "additionalProperties": { + "$ref": "#/$defs/ElicitationContentValue" + } + } + } + }, + "ConnectMcpResponse": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse to `mcp/connect`.", + "type": "object", + "properties": { + "connectionId": { + "description": "The unique identifier for this MCP-over-ACP connection.", + "allOf": [ + { + "$ref": "#/$defs/McpConnectionId" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "connectionId" + ], + "x-side": "client", + "x-method": "mcp/connect" + }, + "DisconnectMcpResponse": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse to `mcp/disconnect`.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "x-side": "client", + "x-method": "mcp/disconnect" + }, + "ClientNotification": { + "description": "A JSON-RPC notification object.", + "type": "object", + "properties": { + "method": { + "description": "The notification method name.", + "type": "string" + }, + "params": { + "description": "Method-specific notification parameters.", + "anyOf": [ + { + "description": "All possible notifications that a client can send to an agent.\n\nThis enum is used internally for routing RPC notifications. You typically won't need\nto use this directly.\n\nNotifications do not expect a response.", + "anyOf": [ + { + "title": "CancelSessionNotification", + "description": "Cancels ongoing operations for a session.\n\nThis is a notification sent by the client to cancel active work in a\nsession.\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- Report an idle `state_update` with `StopReason::Cancelled` after\n cancellation succeeds\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/draft/prompt-lifecycle#cancellation)", + "allOf": [ + { + "$ref": "#/$defs/CancelSessionNotification" + } + ] + }, + { + "title": "DidOpenDocumentNotification", + "description": "**UNSTABLE**\n\nNotification sent when a file is opened in the editor.", + "allOf": [ + { + "$ref": "#/$defs/DidOpenDocumentNotification" + } + ] + }, + { + "title": "DidChangeDocumentNotification", + "description": "**UNSTABLE**\n\nNotification sent when a file is edited.", + "allOf": [ + { + "$ref": "#/$defs/DidChangeDocumentNotification" + } + ] + }, + { + "title": "DidCloseDocumentNotification", + "description": "**UNSTABLE**\n\nNotification sent when a file is closed.", + "allOf": [ + { + "$ref": "#/$defs/DidCloseDocumentNotification" + } + ] + }, + { + "title": "DidSaveDocumentNotification", + "description": "**UNSTABLE**\n\nNotification sent when a file is saved.", + "allOf": [ + { + "$ref": "#/$defs/DidSaveDocumentNotification" + } + ] + }, + { + "title": "DidFocusDocumentNotification", + "description": "**UNSTABLE**\n\nNotification sent when a file becomes the active editor tab.", + "allOf": [ + { + "$ref": "#/$defs/DidFocusDocumentNotification" + } + ] + }, + { + "title": "AcceptNesNotification", + "description": "**UNSTABLE**\n\nNotification sent when a suggestion is accepted.", + "allOf": [ + { + "$ref": "#/$defs/AcceptNesNotification" + } + ] + }, + { + "title": "RejectNesNotification", + "description": "**UNSTABLE**\n\nNotification sent when a suggestion is rejected.", + "allOf": [ + { + "$ref": "#/$defs/RejectNesNotification" + } + ] + }, + { + "title": "MessageMcpNotification", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSends an MCP-over-ACP notification.", + "allOf": [ + { + "$ref": "#/$defs/MessageMcpNotification" + } + ] + }, + { + "title": "ExtNotification", + "description": "Handles extension notifications from the client.\n\nExtension notifications provide a way to send one-way messages for custom functionality\nwhile maintaining protocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "allOf": [ + { + "$ref": "#/$defs/ExtNotification" + } + ] + } + ] + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "method" + ], + "x-docs-ignore": true + }, + "CancelSessionNotification": { + "description": "Notification to cancel ongoing operations for a session.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/draft/prompt-lifecycle#cancellation)", + "type": "object", + "properties": { + "sessionId": { + "description": "The ID of the session to cancel operations for.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId" + ], + "x-side": "agent", + "x-method": "session/cancel" + }, + "DidOpenDocumentNotification": { + "description": "Notification sent when a file is opened in the editor.", + "type": "object", + "properties": { + "sessionId": { + "description": "The session ID for this notification.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "uri": { + "description": "The URI of the opened document.", + "type": "string", + "format": "uri" + }, + "languageId": { + "description": "The language identifier of the document (e.g., \"rust\", \"python\").", + "type": "string" + }, + "version": { + "description": "The version number of the document.", + "type": "integer", + "format": "int64" + }, + "text": { + "description": "The full text content of the document.", + "type": "string" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId", + "uri", + "languageId", + "version", + "text" + ], + "x-side": "agent", + "x-method": "document/didOpen" + }, + "DidChangeDocumentNotification": { + "description": "Notification sent when a file is edited.", + "type": "object", + "properties": { + "sessionId": { + "description": "The session ID for this notification.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "uri": { + "description": "The URI of the changed document.", + "type": "string", + "format": "uri" + }, + "version": { + "description": "The new version number of the document.", + "type": "integer", + "format": "int64" + }, + "contentChanges": { + "description": "The content changes.", + "type": "array", + "items": { + "$ref": "#/$defs/TextDocumentContentChangeEvent" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId", + "uri", + "version", + "contentChanges" + ], + "x-side": "agent", + "x-method": "document/didChange" + }, + "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.", + "type": "object", + "properties": { + "range": { + "description": "The range of the document that changed. If `None`, the entire content is replaced.", + "anyOf": [ + { + "$ref": "#/$defs/Range" + }, + { + "type": "null" + } + ] + }, + "text": { + "description": "The new text for the range, or the full document content if `range` is `None`.", + "type": "string" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "text" + ] + }, + "DidCloseDocumentNotification": { + "description": "Notification sent when a file is closed.", + "type": "object", + "properties": { + "sessionId": { + "description": "The session ID for this notification.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "uri": { + "description": "The URI of the closed document.", + "type": "string", + "format": "uri" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId", + "uri" + ], + "x-side": "agent", + "x-method": "document/didClose" + }, + "DidSaveDocumentNotification": { + "description": "Notification sent when a file is saved.", + "type": "object", + "properties": { + "sessionId": { + "description": "The session ID for this notification.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "uri": { + "description": "The URI of the saved document.", + "type": "string", + "format": "uri" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId", + "uri" + ], + "x-side": "agent", + "x-method": "document/didSave" + }, + "DidFocusDocumentNotification": { + "description": "Notification sent when a file becomes the active editor tab.", + "type": "object", + "properties": { + "sessionId": { + "description": "The session ID for this notification.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "uri": { + "description": "The URI of the focused document.", + "type": "string", + "format": "uri" + }, + "version": { + "description": "The version number of the document.", + "type": "integer", + "format": "int64" + }, + "position": { + "description": "The current cursor position.", + "allOf": [ + { + "$ref": "#/$defs/Position" + } + ] + }, + "visibleRange": { + "description": "The portion of the file currently visible in the editor viewport.", + "allOf": [ + { + "$ref": "#/$defs/Range" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId", + "uri", + "version", + "position", + "visibleRange" + ], + "x-side": "agent", + "x-method": "document/didFocus" + }, + "AcceptNesNotification": { + "description": "Notification sent when a suggestion is accepted.", + "type": "object", + "properties": { + "sessionId": { + "description": "The session ID for this notification.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "suggestionId": { + "description": "The ID of the accepted suggestion.", + "allOf": [ + { + "$ref": "#/$defs/NesSuggestionId" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId", + "suggestionId" + ], + "x-side": "agent", + "x-method": "nes/accept" + }, + "RejectNesNotification": { + "description": "Notification sent when a suggestion is rejected.", + "type": "object", + "properties": { + "sessionId": { + "description": "The session ID for this notification.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "suggestionId": { + "description": "The ID of the rejected suggestion.", + "allOf": [ + { + "$ref": "#/$defs/NesSuggestionId" + } + ] + }, + "reason": { + "description": "The reason for rejection.", + "anyOf": [ + { + "$ref": "#/$defs/NesRejectReason" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId", + "suggestionId" + ], + "x-side": "agent", + "x-method": "nes/reject" + }, + "NesRejectReason": { + "description": "The reason a suggestion was rejected.", + "anyOf": [ + { + "description": "The user explicitly dismissed the suggestion.", + "type": "string", + "const": "rejected" + }, + { + "description": "The suggestion was shown but the user continued editing without interacting.", + "type": "string", + "const": "ignored" + }, + { + "description": "The suggestion was superseded by a newer suggestion.", + "type": "string", + "const": "replaced" + }, + { + "description": "The request was cancelled before the agent returned a response.", + "type": "string", + "const": "cancelled" + }, + { + "title": "Other", + "description": "Custom or future rejection reason.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.", + "type": "string" + } + ] + }, + "ProtocolLevelNotification": { + "description": "A JSON-RPC notification object.", + "type": "object", + "properties": { + "method": { + "description": "The notification method name.", + "type": "string" + }, + "params": { + "description": "Method-specific notification parameters.", + "anyOf": [ + { + "description": "General protocol-level notifications that all sides are expected to\nimplement.\n\nNotifications whose methods start with '$/' are messages which\nare protocol implementation dependent and might not be implementable in all\nclients or agents. For example if the implementation uses a single threaded\nsynchronous programming language then there is little it can do to react to\na `$/cancel_request` notification. If an agent or client receives\nnotifications starting with '$/' it is free to ignore the notification.\n\nNotifications do not expect a response.", + "anyOf": [ + { + "title": "CancelRequestNotification", + "description": "Cancels an ongoing request.\n\nThis is a notification sent by the side that sent a request to cancel that request.\n\nUpon receiving this notification, the receiver:\n\n1. MAY cancel the corresponding request activity and all nested activities\n2. MAY send any pending notifications.\n3. MUST send one of these responses for the original request:\n - Valid response with appropriate data (partial results or cancellation marker)\n - Error response with code `-32800` (Cancelled)\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/draft/cancellation)", + "allOf": [ + { + "$ref": "#/$defs/CancelRequestNotification" + } + ] + } + ] + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "method" + ], + "x-docs-ignore": true + }, + "CancelRequestNotification": { + "description": "Notification to cancel an ongoing request.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v2/draft/cancellation)", + "type": "object", + "properties": { + "requestId": { + "description": "The ID of the request to cancel.", + "allOf": [ + { + "$ref": "#/$defs/RequestId" + } + ] + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "requestId" + ], + "x-side": "protocol", + "x-method": "$/cancel_request" + } + } +} From c794422392a1df04811fd9ccf984d3001401f784 Mon Sep 17 00:00:00 2001 From: PsiACE Date: Tue, 1 Sep 2026 02:07:09 +0800 Subject: [PATCH 2/5] feat(codegen): generate experimental v2 bindings --- Makefile | 10 +- pyproject.toml | 2 + scripts/_schema_semantics.py | 15 +- scripts/gen_all.py | 114 +- scripts/gen_meta.py | 80 +- scripts/gen_schema.py | 16 +- scripts/gen_schema_v2.py | 231 ++ src/acp/_schema_base.py | 41 + src/acp/experimental/__init__.py | 1 + src/acp/experimental/v2/__init__.py | 5 + src/acp/experimental/v2/meta.py | 40 + src/acp/experimental/v2/schema.py | 5978 +++++++++++++++++++++++++++ 12 files changed, 6471 insertions(+), 62 deletions(-) create mode 100644 scripts/gen_schema_v2.py create mode 100644 src/acp/experimental/__init__.py create mode 100644 src/acp/experimental/v2/__init__.py create mode 100644 src/acp/experimental/v2/meta.py create mode 100644 src/acp/experimental/v2/schema.py diff --git a/Makefile b/Makefile index 7b097c5..3efd7a0 100644 --- a/Makefile +++ b/Makefile @@ -11,10 +11,18 @@ gen-all: ## Generate all code from schema @uv run ruff check --fix @uv run ruff format . +.PHONY: gen-v2 +gen-v2: ## Generate experimental v2 schema bindings + @echo "🚀 Generating experimental v2 schema bindings" + @uv run scripts/gen_all.py --protocol-version 2 + .PHONY: gen-check gen-check: ## Verify generated schema bindings without changing the worktree @echo "🚀 Checking generated schema bindings" @uv run --frozen python -m scripts.gen_schema --check + @uv run --frozen python -m scripts.gen_meta --check + @uv run --frozen python -m scripts.gen_schema --protocol-version 2 --check + @uv run --frozen python -m scripts.gen_meta --protocol-version 2 --check .PHONY: check check: ## Run code quality tools. @@ -23,7 +31,7 @@ check: ## Run code quality tools. @echo "🚀 Linting code: Running pre-commit via prek" @uv run prek run -a @echo "🚀 Static type checking: Running ty" - @uv run ty check --exclude "src/acp/meta.py" --exclude "src/acp/schema.py" --exclude "examples/*.py" + @uv run ty check --exclude "src/acp/meta.py" --exclude "src/acp/schema.py" --exclude "src/acp/experimental/v2/meta.py" --exclude "src/acp/experimental/v2/schema.py" --exclude "examples/*.py" @echo "🚀 Checking for obsolete dependencies: Running deptry" @uv run deptry src diff --git a/pyproject.toml b/pyproject.toml index 5934086..ffbd061 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -120,6 +120,8 @@ ignore = [ "tests/*" = ["S101"] "src/acp/meta.py" = ["ALL"] "src/acp/schema.py" = ["ALL"] +"src/acp/experimental/v2/meta.py" = ["ALL"] +"src/acp/experimental/v2/schema.py" = ["ALL"] [tool.ruff.format] preview = true diff --git a/scripts/_schema_semantics.py b/scripts/_schema_semantics.py index b07572e..4784267 100644 --- a/scripts/_schema_semantics.py +++ b/scripts/_schema_semantics.py @@ -7,7 +7,12 @@ ROOT = Path(__file__).resolve().parents[1] -DEFAULT_SEMANTICS_MODULE = "scripts.gen_schema_v1" +DEFAULT_PROTOCOL_VERSION = 1 +SEMANTIC_MODULES = { + 1: "scripts.gen_schema_v1", + 2: "scripts.gen_schema_v2", +} +SUPPORTED_PROTOCOL_VERSIONS = tuple(SEMANTIC_MODULES) @dataclass(frozen=True, slots=True) @@ -23,8 +28,12 @@ class _SemanticsModule(Protocol): SEMANTICS: SchemaSemantics -def get_default_schema_semantics() -> SchemaSemantics: - module = cast(_SemanticsModule, import_module(DEFAULT_SEMANTICS_MODULE)) +def get_schema_semantics(protocol_version: int) -> SchemaSemantics: + try: + module_name = SEMANTIC_MODULES[protocol_version] + except KeyError: + raise ValueError(f"Unsupported protocol version: {protocol_version}") from None + module = cast(_SemanticsModule, import_module(module_name)) return module.SEMANTICS diff --git a/scripts/gen_all.py b/scripts/gen_all.py index 53d4fe9..4e0375c 100644 --- a/scripts/gen_all.py +++ b/scripts/gen_all.py @@ -18,13 +18,11 @@ from scripts import gen_meta, gen_schema, gen_signature # noqa: E402 pylint: disable=wrong-import-position SCHEMA_DIR = ROOT / "schema" -SCHEMA_JSON = SCHEMA_DIR / "schema.json" -META_JSON = SCHEMA_DIR / "meta.json" -VERSION_FILE = SCHEMA_DIR / "VERSION" DEFAULT_REPO = "agentclientprotocol/agent-client-protocol" LEGACY_SCHEMA_PATHS = ("schema/schema.unstable.json", "schema/meta.unstable.json") V1_SCHEMA_PATHS = ("schema/v1/schema.unstable.json", "schema/v1/meta.unstable.json") +V2_SCHEMA_PATHS = ("schema/v2/schema.unstable.json", "schema/v2/meta.unstable.json") def parse_args() -> argparse.Namespace: @@ -42,6 +40,13 @@ def parse_args() -> argparse.Namespace: default=os.environ.get("ACP_SCHEMA_REPO", DEFAULT_REPO), help="Source repository providing schema.json/meta.json (default: %(default)s)", ) + parser.add_argument( + "--protocol-version", + type=int, + choices=(1, 2), + default=int(os.environ.get("ACP_SCHEMA_PROTOCOL", "1")), + help="Protocol bindings to generate (default: %(default)s)", + ) parser.add_argument( "--no-download", action="store_true", @@ -67,23 +72,30 @@ def main() -> None: version = args.version or os.environ.get("ACP_SCHEMA_VERSION") repo = args.repo - should_download = _should_download(args, version) + protocol_version = args.protocol_version + schema_dir = _schema_dir(protocol_version) + schema_json = schema_dir / "schema.json" + meta_json = schema_dir / "meta.json" + should_download = _should_download(args, version, protocol_version) if should_download: ref = resolve_ref(version) - download_schema(repo, ref) + download_schema(repo, ref, protocol_version) else: - ref = resolve_ref(version) if version else _cached_ref() + ref = resolve_ref(version) if version else _cached_ref(protocol_version) - if not (SCHEMA_JSON.exists() and META_JSON.exists()): - print("schema/schema.json or schema/meta.json missing; run with --version to fetch them.", file=sys.stderr) + if not (schema_json.exists() and meta_json.exists()): + print( + f"{schema_dir.relative_to(ROOT)} is missing schema.json or meta.json; run with --version.", file=sys.stderr + ) sys.exit(1) - gen_schema.generate_schema() - gen_meta.generate_meta() - gen_signature.gen_signature(ROOT / "src" / "acp") + gen_schema.generate_schema(protocol_version=protocol_version) + gen_meta.generate_meta(protocol_version=protocol_version) + if protocol_version == 1: + gen_signature.gen_signature(ROOT / "src" / "acp") if args.format_output: - format_generated_files() + format_generated_files(protocol_version) if ref: print(f"Generated schema using ref: {ref}") @@ -91,32 +103,41 @@ def main() -> None: print("Generated schema using local schema files") -def format_generated_files() -> None: - files = [ - ROOT / "src" / "acp" / "schema.py", - ROOT / "src" / "acp" / "meta.py", - ROOT / "src" / "acp" / "interfaces.py", - ROOT / "src" / "acp" / "agent" / "connection.py", - ROOT / "src" / "acp" / "client" / "connection.py", - ] +def format_generated_files(protocol_version: int) -> None: + if protocol_version == 1: + files = [ + ROOT / "src" / "acp" / "schema.py", + ROOT / "src" / "acp" / "meta.py", + ROOT / "src" / "acp" / "interfaces.py", + ROOT / "src" / "acp" / "agent" / "connection.py", + ROOT / "src" / "acp" / "client" / "connection.py", + ] + else: + files = [ + ROOT / "src" / "acp" / "experimental" / "v2" / "schema.py", + ROOT / "src" / "acp" / "experimental" / "v2" / "meta.py", + ] subprocess.check_call([sys.executable, "-m", "ruff", "check", "--fix", *(str(path) for path in files)]) # noqa: S603 subprocess.check_call([sys.executable, "-m", "ruff", "format", *(str(path) for path in files)]) # noqa: S603 -def _should_download(args: argparse.Namespace, version: str | None) -> bool: +def _should_download(args: argparse.Namespace, version: str | None, protocol_version: int) -> bool: + schema_dir = _schema_dir(protocol_version) + schema_json = schema_dir / "schema.json" + meta_json = schema_dir / "meta.json" env_override = os.environ.get("ACP_SCHEMA_DOWNLOAD") if env_override is not None: return env_override.lower() in {"1", "true", "yes"} if args.no_download: return False if version: - if not SCHEMA_JSON.exists() or not META_JSON.exists(): + if not schema_json.exists() or not meta_json.exists(): return True - cached = _cached_ref() + cached = _cached_ref(protocol_version) if args.force: return True return cached != resolve_ref(version) - return not (SCHEMA_JSON.exists() and META_JSON.exists()) + return not (schema_json.exists() and meta_json.exists()) def resolve_ref(version: str | None) -> str: @@ -124,31 +145,35 @@ def resolve_ref(version: str | None) -> str: return "refs/heads/main" if version.startswith("refs/"): return version - if re.fullmatch(r"schema-v\d+\.\d+\.\d+", version): + if re.fullmatch(r"schema-v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?", version): return f"refs/tags/{version}" - if re.fullmatch(r"v?\d+\.\d+\.\d+", version): + if re.fullmatch(r"v?\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?", version): value = version if version.startswith("v") else f"v{version}" return f"refs/tags/{value}" return f"refs/heads/{version}" -def download_schema(repo: str, ref: str) -> None: - SCHEMA_DIR.mkdir(parents=True, exist_ok=True) +def download_schema(repo: str, ref: str, protocol_version: int = 1) -> None: + schema_dir = _schema_dir(protocol_version) + schema_json = schema_dir / "schema.json" + meta_json = schema_dir / "meta.json" + version_file = schema_dir / "VERSION" + schema_dir.mkdir(parents=True, exist_ok=True) try: - schema_data, meta_data = fetch_schema_pair(repo, ref) + schema_data, meta_data = fetch_schema_pair(repo, ref, protocol_version) except RuntimeError as exc: # pragma: no cover - network error path print(exc, file=sys.stderr) sys.exit(1) - SCHEMA_JSON.write_text(json.dumps(schema_data, indent=2) + "\n", encoding="utf-8") - META_JSON.write_text(json.dumps(meta_data, indent=2) + "\n", encoding="utf-8") - VERSION_FILE.write_text(ref + "\n", encoding="utf-8") + schema_json.write_text(json.dumps(schema_data, indent=2) + "\n", encoding="utf-8") + meta_json.write_text(json.dumps(meta_data, indent=2) + "\n", encoding="utf-8") + version_file.write_text(ref + "\n", encoding="utf-8") print(f"Fetched schema and meta from {repo}@{ref}") -def fetch_schema_pair(repo: str, ref: str) -> tuple[dict, dict]: +def fetch_schema_pair(repo: str, ref: str, protocol_version: int = 1) -> tuple[dict, dict]: errors = [] - for schema_path, meta_path in schema_source_paths(ref): + for schema_path, meta_path in schema_source_paths(ref, protocol_version): schema_url = f"https://raw.githubusercontent.com/{repo}/{ref}/{schema_path}" meta_url = f"https://raw.githubusercontent.com/{repo}/{ref}/{meta_path}" try: @@ -160,8 +185,10 @@ def fetch_schema_pair(repo: str, ref: str) -> tuple[dict, dict]: raise RuntimeError(f"Failed to fetch schema and meta from {repo}@{ref}. Attempts:\n{attempted}") -def schema_source_paths(ref: str) -> tuple[tuple[str, str], ...]: - if re.fullmatch(r"refs/tags/schema-v\d+\.\d+\.\d+", ref): +def schema_source_paths(ref: str, protocol_version: int = 1) -> tuple[tuple[str, str], ...]: + if protocol_version == 2: + return (V2_SCHEMA_PATHS,) + if re.fullmatch(r"refs/tags/schema-v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?", ref): return (V1_SCHEMA_PATHS, LEGACY_SCHEMA_PATHS) return (LEGACY_SCHEMA_PATHS, V1_SCHEMA_PATHS) @@ -174,9 +201,18 @@ def fetch_json(url: str) -> dict: raise RuntimeError(f"Failed to fetch {url}: {exc}") from exc -def _cached_ref() -> str | None: - if VERSION_FILE.exists(): - return VERSION_FILE.read_text(encoding="utf-8").strip() or None +def _schema_dir(protocol_version: int) -> Path: + if protocol_version == 1: + return SCHEMA_DIR + if protocol_version == 2: + return SCHEMA_DIR / "v2" + raise ValueError(f"Unsupported protocol version: {protocol_version}") + + +def _cached_ref(protocol_version: int) -> str | None: + version_file = _schema_dir(protocol_version) / "VERSION" + if version_file.exists(): + return version_file.read_text(encoding="utf-8").strip() or None return None diff --git a/scripts/gen_meta.py b/scripts/gen_meta.py index f6082e5..f423269 100644 --- a/scripts/gen_meta.py +++ b/scripts/gen_meta.py @@ -1,42 +1,92 @@ #!/usr/bin/env python3 from __future__ import annotations +import argparse +import difflib import json +import subprocess +import sys from pathlib import Path ROOT = Path(__file__).resolve().parents[1] -SCHEMA_DIR = ROOT / "schema" -VERSION_FILE = SCHEMA_DIR / "VERSION" def main() -> None: - generate_meta() + parser = argparse.ArgumentParser(description="Generate ACP method metadata.") + parser.add_argument("--protocol-version", type=int, choices=(1, 2), default=1) + parser.add_argument("--check", action="store_true", help="Fail if the committed metadata is stale.") + args = parser.parse_args() + if not generate_meta(protocol_version=args.protocol_version, check=args.check): + raise SystemExit(1) -def generate_meta() -> None: - meta_json = SCHEMA_DIR / "meta.json" - out_py = ROOT / "src" / "acp" / "meta.py" +def generate_meta(*, protocol_version: int = 1, check: bool = False) -> bool: + _, out_py = _generation_paths(protocol_version) + candidate = render_meta(protocol_version=protocol_version) + current = out_py.read_text(encoding="utf-8") if out_py.exists() else "" + if check: + if current == candidate: + return True + print( + "".join( + difflib.unified_diff( + current.splitlines(keepends=True), + candidate.splitlines(keepends=True), + fromfile=str(out_py.relative_to(ROOT)), + tofile=f"{out_py.relative_to(ROOT)} (generated)", + ) + ), + end="", + ) + return False + out_py.parent.mkdir(parents=True, exist_ok=True) + out_py.write_text(candidate, encoding="utf-8") + return True + + +def render_meta(*, protocol_version: int = 1) -> str: + schema_dir, out_py = _generation_paths(protocol_version) + meta_json = schema_dir / "meta.json" + version_file = schema_dir / "VERSION" if not meta_json.exists(): - raise SystemExit("schema/meta.json not found. Run gen_schema.py first.") + raise SystemExit(f"{meta_json.relative_to(ROOT)} not found. Run gen_all.py first.") data = json.loads(meta_json.read_text("utf-8")) agent_methods = data.get("agentMethods", {}) client_methods = data.get("clientMethods", {}) version = data.get("version", 1) - header_lines = ["# Generated from schema/meta.json. Do not edit by hand."] - if VERSION_FILE.exists(): - ref = VERSION_FILE.read_text("utf-8").strip() + header_lines = [f"# Generated from {meta_json.relative_to(ROOT)}. Do not edit by hand."] + if version_file.exists(): + ref = version_file.read_text("utf-8").strip() if ref: header_lines.append(f"# Schema ref: {ref}") - out_py.write_text( + source = ( "\n".join(header_lines) + "\n" - + f"AGENT_METHODS = {agent_methods!r}\n" - + f"CLIENT_METHODS = {client_methods!r}\n" - + f"PROTOCOL_VERSION = {int(version)}\n", - encoding="utf-8", + + f"AGENT_METHODS = {json.dumps(agent_methods, indent=4)}\n" + + f"CLIENT_METHODS = {json.dumps(client_methods, indent=4)}\n" + + f"PROTOCOL_VERSION = {int(version)}\n" + ) + result = subprocess.run( # noqa: S603 + [sys.executable, "-m", "ruff", "format", "--stdin-filename", str(out_py), "-"], + input=source, + text=True, + capture_output=True, + check=False, + cwd=ROOT, ) + if result.returncode: + raise RuntimeError(f"ruff format failed:\n{result.stderr}") + return result.stdout + + +def _generation_paths(protocol_version: int) -> tuple[Path, Path]: + if protocol_version == 1: + return ROOT / "schema", ROOT / "src" / "acp" / "meta.py" + if protocol_version == 2: + return ROOT / "schema" / "v2", ROOT / "src" / "acp" / "experimental" / "v2" / "meta.py" + raise ValueError(f"Unsupported protocol version: {protocol_version}") if __name__ == "__main__": diff --git a/scripts/gen_schema.py b/scripts/gen_schema.py index 8676f28..8c6de65 100644 --- a/scripts/gen_schema.py +++ b/scripts/gen_schema.py @@ -26,8 +26,10 @@ sys.path.append(str(ROOT)) from scripts._schema_semantics import ( # noqa: E402 + DEFAULT_PROTOCOL_VERSION, + SUPPORTED_PROTOCOL_VERSIONS, SchemaSemantics, - get_default_schema_semantics, + get_schema_semantics, ) UNSIGNED_TYPE_MAPPINGS = ( @@ -40,17 +42,23 @@ def parse_args() -> argparse.Namespace: parser = argparse.ArgumentParser(description="Generate ACP schema bindings.") parser.add_argument("--check", action="store_true", help="Fail if the committed bindings are stale.") + parser.add_argument( + "--protocol-version", + type=int, + choices=SUPPORTED_PROTOCOL_VERSIONS, + default=DEFAULT_PROTOCOL_VERSION, + ) return parser.parse_args() def main() -> None: args = parse_args() - if not generate_schema(check=args.check): + if not generate_schema(check=args.check, protocol_version=args.protocol_version): raise SystemExit(1) -def generate_schema(*, check: bool = False) -> bool: - semantics = get_default_schema_semantics() +def generate_schema(*, check: bool = False, protocol_version: int = DEFAULT_PROTOCOL_VERSION) -> bool: + semantics = get_schema_semantics(protocol_version) candidate = render_schema(semantics) schema_out = semantics.schema_out current = schema_out.read_text(encoding="utf-8") if schema_out.exists() else "" diff --git a/scripts/gen_schema_v2.py b/scripts/gen_schema_v2.py new file mode 100644 index 0000000..00fb4f4 --- /dev/null +++ b/scripts/gen_schema_v2.py @@ -0,0 +1,231 @@ +from __future__ import annotations + +from ._schema_semantics import ( + ROOT, + SchemaSemantics, + inline_model_ref, + variant_model_map, +) + +MODEL_NAME_MAP = { + "#/$defs/AvailableCommandsUpdate": "AvailableCommandsUpdateBase", + "#/$defs/ConfigOptionUpdate": "ConfigOptionUpdateBase", + "#/$defs/SessionInfoUpdate": "SessionInfoUpdateBase", + "#/$defs/StringMultiSelectItems": "StringMultiSelectItemsBase", + "#/$defs/UsageUpdate": "UsageUpdateBase", +} +for variant_names in ( + variant_model_map("AgentResponse", "anyOf", "object", ("AgentResponseMessage", "AgentErrorMessage")), + variant_model_map("ClientResponse", "anyOf", "object", ("ClientResponseMessage", "ClientErrorMessage")), + variant_model_map("AuthMethod", "anyOf", "allOf", ("TerminalAuthMethod", "AgentAuthMethod")), + variant_model_map("AvailableCommandInput", "anyOf", "allOf", ("TextAvailableCommandInput",)), + variant_model_map( + "ContentBlock", + "anyOf", + "allOf", + ( + "TextContentBlock", + "ImageContentBlock", + "AudioContentBlock", + "ResourceContentBlock", + "EmbeddedResourceContentBlock", + ), + ), + variant_model_map( + "DiffChange", + "anyOf", + "allOf", + ("AddDiffChange", "DeleteDiffChange", "ModifyDiffChange", "MoveDiffChange", "CopyDiffChange"), + ), + variant_model_map("McpServer", "anyOf", "allOf", ("HttpMcpServer", "AcpMcpServer", "StdioMcpServer")), + variant_model_map("ReplayFrom", "anyOf", "allOf", ("ReplayFromStartVariant",)), + variant_model_map( + "RequestPermissionSubject", + "anyOf", + "allOf", + ("ToolCallPermissionSubjectVariant", "CommandPermissionSubjectVariant"), + ), + variant_model_map( + "SessionConfigOption", + "anyOf", + "allOf", + ("SelectSessionConfigOption", "BooleanSessionConfigOption"), + ), + variant_model_map( + "StateUpdate", + "anyOf", + "allOf", + ("RunningState", "IdleState", "RequiresActionState"), + ), + variant_model_map( + "ToolCallContent", + "anyOf", + "allOf", + ("ContentToolCallContent", "DiffToolCallContent", "TerminalToolCallContent"), + ), + variant_model_map( + "PlanUpdateContent", + "anyOf", + "allOf", + ("PlanUpdateItems", "PlanUpdateFile", "PlanUpdateMarkdown"), + ), + variant_model_map( + "NesSuggestion", + "anyOf", + "allOf", + ( + "NesEditSuggestionVariant", + "NesJumpSuggestionVariant", + "NesRenameSuggestionVariant", + "NesSearchAndReplaceSuggestionVariant", + ), + ), + variant_model_map( + "ElicitationFormMode", + "anyOf", + "allOf", + ("ElicitationFormSessionMode", "ElicitationFormRequestMode"), + ), + variant_model_map( + "ElicitationUrlMode", + "anyOf", + "allOf", + ("ElicitationUrlSessionMode", "ElicitationUrlRequestMode"), + ), + variant_model_map( + "ElicitationPropertySchema", + "anyOf", + "allOf", + ( + "ElicitationStringPropertySchema", + "ElicitationNumberPropertySchema", + "ElicitationIntegerPropertySchema", + "ElicitationBooleanPropertySchema", + "ElicitationMultiSelectPropertySchema", + ), + ), + variant_model_map("MultiSelectItems", "anyOf", "allOf", ("StringMultiSelectItems",)), + variant_model_map( + "SessionUpdate", + "anyOf", + "allOf", + ( + "UserMessageChunk", + "UserMessageUpdate", + "AgentMessageChunk", + "AgentMessageUpdate", + "AgentThoughtChunk", + "AgentThoughtUpdate", + "SessionStateUpdate", + "ToolCallContentChunkUpdate", + "SessionToolCallUpdate", + "SessionTerminalUpdate", + "SessionTerminalOutputChunk", + "SessionPlanUpdate", + "SessionPlanRemovedUpdate", + "AvailableCommandsUpdate", + "ConfigOptionUpdate", + "SessionInfoUpdate", + "UsageUpdate", + "SessionCompactionUpdate", + "SessionCompactionSummaryChunk", + ), + ), +): + MODEL_NAME_MAP.update(variant_names) + +MODEL_NAME_MAP.update({ + inline_model_ref("AuthMethod", ("anyOf", 2), ("object", None)): "OtherAuthMethod", + inline_model_ref("AvailableCommandInput", ("anyOf", 1), ("object", None)): "OtherAvailableCommandInput", + inline_model_ref("ContentBlock", ("anyOf", 5), ("object", None)): "OtherContentBlock", + inline_model_ref("DiffChange", ("anyOf", 5), ("object", None)): "OtherDiffChange", + inline_model_ref("McpServer", ("anyOf", 3), ("object", None)): "OtherMcpServer", + inline_model_ref("ReplayFrom", ("anyOf", 1), ("object", None)): "OtherReplayFrom", + inline_model_ref("RequestPermissionOutcome", ("anyOf", 0), ("object", None)): ("CancelledPermissionOutcome"), + inline_model_ref("RequestPermissionOutcome", ("anyOf", 1), ("allOf", None)): ("SelectedPermissionOutcomeVariant"), + inline_model_ref("RequestPermissionOutcome", ("anyOf", 2), ("object", None)): "OtherPermissionOutcome", + inline_model_ref("RequestPermissionSubject", ("anyOf", 2), ("object", None)): "OtherPermissionSubject", + inline_model_ref("SessionConfigOption", ("anyOf", 2), ("object", None)): "OtherSessionConfigOption", + inline_model_ref("SetSessionConfigOptionRequest", ("anyOf", 0), ("object", None)): ( + "SetSessionConfigOptionIdRequest" + ), + inline_model_ref("SetSessionConfigOptionRequest", ("anyOf", 1), ("object", None)): ( + "SetSessionConfigOptionBooleanRequest" + ), + inline_model_ref("SetSessionConfigOptionRequest", ("anyOf", 2), ("object", None)): ( + "SetSessionConfigOptionOtherRequest" + ), + inline_model_ref("StateUpdate", ("anyOf", 3), ("object", None)): "OtherState", + inline_model_ref("ToolCallContent", ("anyOf", 3), ("object", None)): "OtherToolCallContent", + inline_model_ref("PlanUpdateContent", ("anyOf", 3), ("object", None)): "OtherPlanUpdateContent", + inline_model_ref("NesSuggestion", ("anyOf", 4), ("object", None)): "OtherNesSuggestion", + inline_model_ref("ElicitationPropertySchema", ("anyOf", 5), ("object", None)): ("ElicitationOtherPropertySchema"), + inline_model_ref("MultiSelectItems", ("anyOf", 1), ("object", None)): "OtherMultiSelectItems", + inline_model_ref("SessionUpdate", ("anyOf", 19), ("object", None)): "OtherSessionUpdate", + inline_model_ref("SessionUpdate", ("anyOf", 6), ("allOf", 0), ("allOf", None)): ("RunningSessionStateUpdateBase"), + inline_model_ref("SessionUpdate", ("anyOf", 6), ("allOf", 1), ("allOf", None)): ("IdleSessionStateUpdateBase"), + inline_model_ref("SessionUpdate", ("anyOf", 6), ("allOf", 2), ("allOf", None)): ( + "RequiresActionSessionStateUpdateBase" + ), + inline_model_ref("SessionUpdate", ("anyOf", 6), ("allOf", 3), ("object", None)): ("OtherSessionStateUpdateBase"), + inline_model_ref("SessionUpdate", ("anyOf", 6), ("allOf", None), ("allOf", None)): ("SessionStateUpdateBase"), +}) +for index, name in enumerate(( + "RunningSessionStateUpdate", + "IdleSessionStateUpdate", + "RequiresActionSessionStateUpdate", + "OtherSessionStateUpdate", +)): + MODEL_NAME_MAP[inline_model_ref("SessionUpdate", ("anyOf", 6), ("allOf", None), (f"union_model-{index}", None))] = ( + name + ) + +MODEL_NAME_MAP.update({ + inline_model_ref("CreateElicitationResponse", ("anyOf", 0), ("allOf", None)): "AcceptElicitationResponse", + inline_model_ref("CreateElicitationResponse", ("anyOf", 1), ("object", None)): "DeclineElicitationResponse", + inline_model_ref("CreateElicitationResponse", ("anyOf", 2), ("object", None)): "CancelElicitationResponse", + inline_model_ref("CreateElicitationResponse", ("anyOf", 3), ("object", None)): "OtherElicitationResponse", + inline_model_ref("CreateElicitationRequest", ("anyOf", 0), ("allOf", None), ("allOf", None)): ( + "CreateFormElicitationRequestBase" + ), + inline_model_ref("CreateElicitationRequest", ("anyOf", 0), ("allOf", 0), ("allOf", None)): ( + "CreateFormSessionElicitationRequestBase" + ), + inline_model_ref("CreateElicitationRequest", ("anyOf", 0), ("allOf", 1), ("allOf", None)): ( + "CreateFormRequestElicitationRequestBase" + ), + inline_model_ref("CreateElicitationRequest", ("anyOf", 0), ("allOf", None), ("union_model-0", None)): ( + "CreateFormSessionElicitationRequest" + ), + inline_model_ref("CreateElicitationRequest", ("anyOf", 0), ("allOf", None), ("union_model-1", None)): ( + "CreateFormRequestElicitationRequest" + ), + inline_model_ref("CreateElicitationRequest", ("anyOf", 1), ("allOf", None), ("allOf", None)): ( + "CreateUrlElicitationRequestBase" + ), + inline_model_ref("CreateElicitationRequest", ("anyOf", 1), ("allOf", 0), ("allOf", None)): ( + "CreateUrlSessionElicitationRequestBase" + ), + inline_model_ref("CreateElicitationRequest", ("anyOf", 1), ("allOf", 1), ("allOf", None)): ( + "CreateUrlRequestElicitationRequestBase" + ), + inline_model_ref("CreateElicitationRequest", ("anyOf", 1), ("allOf", None), ("union_model-0", None)): ( + "CreateUrlSessionElicitationRequest" + ), + inline_model_ref("CreateElicitationRequest", ("anyOf", 1), ("allOf", None), ("union_model-1", None)): ( + "CreateUrlRequestElicitationRequest" + ), + inline_model_ref("CreateElicitationRequest", ("anyOf", 2), ("anyOf", 0), ("allOf", None)): ( + "CreateOtherSessionElicitationRequest" + ), + inline_model_ref("CreateElicitationRequest", ("anyOf", 2), ("anyOf", 1), ("allOf", None)): ( + "CreateOtherRequestElicitationRequest" + ), +}) + +SEMANTICS = SchemaSemantics( + schema_json=ROOT / "schema" / "v2" / "schema.json", + version_file=ROOT / "schema" / "v2" / "VERSION", + schema_out=ROOT / "src" / "acp" / "experimental" / "v2" / "schema.py", + model_name_map=MODEL_NAME_MAP, +) diff --git a/src/acp/_schema_base.py b/src/acp/_schema_base.py index ad979b3..282c529 100644 --- a/src/acp/_schema_base.py +++ b/src/acp/_schema_base.py @@ -19,7 +19,48 @@ class BaseModel(pydantic.BaseModel): """Runtime behavior shared by generated ACP schema models.""" + # datamodel-code-generator does not emit the `not` constraints used by ACP's + # open unions, so catch-all variants must reject tags owned by known variants. _reserved_tags: ClassVar[dict[str, tuple[str, frozenset[str]]]] = { + "OtherAuthMethod": ("type", frozenset({"agent", "terminal"})), + "OtherAvailableCommandInput": ("type", frozenset({"text"})), + "OtherContentBlock": ("type", frozenset({"audio", "image", "resource", "resource_link", "text"})), + "OtherDiffChange": ("operation", frozenset({"add", "copy", "delete", "modify", "move"})), + "OtherMcpServer": ("type", frozenset({"acp", "http", "stdio"})), + "OtherNesSuggestion": ("kind", frozenset({"edit", "jump", "rename", "searchAndReplace"})), + "OtherPermissionOutcome": ("outcome", frozenset({"cancelled", "selected"})), + "OtherPermissionSubject": ("type", frozenset({"command", "tool_call"})), + "OtherPlanUpdateContent": ("type", frozenset({"file", "items", "markdown"})), + "OtherReplayFrom": ("type", frozenset({"start"})), + "OtherSessionConfigOption": ("type", frozenset({"boolean", "select"})), + "OtherSessionStateUpdate": ("state", frozenset({"idle", "requires_action", "running"})), + "OtherSessionUpdate": ( + "sessionUpdate", + frozenset({ + "agent_message", + "agent_message_chunk", + "agent_thought", + "agent_thought_chunk", + "available_commands_update", + "compaction_summary_chunk", + "compaction_update", + "config_option_update", + "plan_removed", + "plan_update", + "session_info_update", + "state_update", + "terminal_output_chunk", + "terminal_update", + "tool_call_content_chunk", + "tool_call_update", + "usage_update", + "user_message", + "user_message_chunk", + }), + ), + "OtherState": ("state", frozenset({"idle", "requires_action", "running"})), + "OtherToolCallContent": ("type", frozenset({"content", "diff", "terminal"})), + "SetSessionConfigOptionOtherRequest": ("type", frozenset({"boolean", "id"})), "CreateOtherSessionElicitationRequest": ("mode", frozenset({"form", "url"})), "CreateOtherRequestElicitationRequest": ("mode", frozenset({"form", "url"})), "OtherElicitationResponse": ("action", frozenset({"accept", "cancel", "decline"})), diff --git a/src/acp/experimental/__init__.py b/src/acp/experimental/__init__.py new file mode 100644 index 0000000..82703aa --- /dev/null +++ b/src/acp/experimental/__init__.py @@ -0,0 +1 @@ +"""Experimental ACP APIs.""" diff --git a/src/acp/experimental/v2/__init__.py b/src/acp/experimental/v2/__init__.py new file mode 100644 index 0000000..b50388a --- /dev/null +++ b/src/acp/experimental/v2/__init__.py @@ -0,0 +1,5 @@ +"""Experimental ACP protocol v2 bindings.""" + +from .meta import AGENT_METHODS, CLIENT_METHODS, PROTOCOL_VERSION + +__all__ = ["AGENT_METHODS", "CLIENT_METHODS", "PROTOCOL_VERSION"] diff --git a/src/acp/experimental/v2/meta.py b/src/acp/experimental/v2/meta.py new file mode 100644 index 0000000..ad96d06 --- /dev/null +++ b/src/acp/experimental/v2/meta.py @@ -0,0 +1,40 @@ +# Generated from schema/v2/meta.json. Do not edit by hand. +# Schema ref: refs/tags/schema-v2.0.0-alpha.3 +AGENT_METHODS = { + "initialize": "initialize", + "auth_login": "auth/login", + "providers_list": "providers/list", + "providers_set": "providers/set", + "providers_disable": "providers/disable", + "session_new": "session/new", + "session_set_config_option": "session/set_config_option", + "session_prompt": "session/prompt", + "session_cancel": "session/cancel", + "mcp_message": "mcp/message", + "session_list": "session/list", + "session_delete": "session/delete", + "session_fork": "session/fork", + "session_resume": "session/resume", + "session_close": "session/close", + "auth_logout": "auth/logout", + "nes_start": "nes/start", + "nes_suggest": "nes/suggest", + "nes_accept": "nes/accept", + "nes_reject": "nes/reject", + "nes_close": "nes/close", + "document_did_open": "document/didOpen", + "document_did_change": "document/didChange", + "document_did_close": "document/didClose", + "document_did_save": "document/didSave", + "document_did_focus": "document/didFocus", +} +CLIENT_METHODS = { + "session_request_permission": "session/request_permission", + "session_update": "session/update", + "mcp_connect": "mcp/connect", + "mcp_message": "mcp/message", + "mcp_disconnect": "mcp/disconnect", + "elicitation_create": "elicitation/create", + "elicitation_complete": "elicitation/complete", +} +PROTOCOL_VERSION = 2 diff --git a/src/acp/experimental/v2/schema.py b/src/acp/experimental/v2/schema.py new file mode 100644 index 0000000..6c3b5e5 --- /dev/null +++ b/src/acp/experimental/v2/schema.py @@ -0,0 +1,5978 @@ +# Generated from schema/v2/schema.json. Do not edit by hand. +# Schema ref: refs/tags/schema-v2.0.0-alpha.3 + +from __future__ import annotations + +from enum import Enum +from typing import Annotated, Any, Dict, List, Literal, Optional, Union + +from acp._deserialize import coerce_protocol_version, skip_invalid_items, use_default_on_error +from acp._schema_base import BaseModel +from pydantic import ( + AnyUrl, + AwareDatetime, + ConfigDict, + Field, + RootModel, + ValidationInfo, + ValidatorFunctionWrapHandler, + field_validator, +) + + +class OtherPermissionSubject(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + type: str + """ + Custom or future permission subject type. + + Values beginning with `_` are reserved for implementation-specific + extensions. Unknown values that do not begin with `_` are reserved for + future ACP variants. + """ + + +class OtherToolCallContent(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + type: str + """ + Custom or future tool call content type. + + Values beginning with `_` are reserved for implementation-specific + extensions. Unknown values that do not begin with `_` are reserved for + future ACP variants. + """ + + +class OtherContentBlock(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + type: str + """ + Custom or future content block type. + + Values beginning with `_` are reserved for implementation-specific + extensions. Unknown values that do not begin with `_` are reserved for + future ACP variants. + """ + + +class TextResourceContents(BaseModel): + text: str + """ + Text payload carried by this content block. + """ + uri: AnyUrl + """ + URI associated with this resource or media payload. + """ + mime_type: Annotated[Optional[str], Field(alias="mimeType")] = None + """ + MIME type describing the encoded media payload. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("mime_type", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class BlobResourceContents(BaseModel): + blob: Annotated[str, Field(json_schema_extra={"contentEncoding": "base64"})] + """ + Base64-encoded bytes for a binary resource payload. + """ + uri: AnyUrl + """ + URI associated with this resource or media payload. + """ + mime_type: Annotated[Optional[str], Field(alias="mimeType")] = None + """ + MIME type describing the encoded media payload. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("mime_type", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class DiffPathChange(BaseModel): + path: str + """ + Absolute path for the operation. + """ + + +class DiffPathPairChange(BaseModel): + old_path: Annotated[str, Field(alias="oldPath")] + """ + Absolute path before the operation. + """ + path: str + """ + Absolute path after the operation. + """ + + +class Terminal(BaseModel): + terminal_id: Annotated[str, Field(alias="terminalId")] + """ + The ID of the terminal to display. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. This metadata is scoped to the content reference. Omitted + and `null` are equivalent and mean no item metadata was provided. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + +class ToolCallLocation(BaseModel): + path: str + """ + The absolute file path being accessed or modified. + """ + line: Annotated[Optional[int], Field(ge=0)] = None + """ + Optional line number within the file. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("line", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class CommandPermissionSubject(BaseModel): + command: str + """ + The command that would be run if permission is granted. + """ + cwd: str + """ + The absolute working directory for the command. + """ + tool_call_id: Annotated[Optional[str], Field(alias="toolCallId")] = None + """ + The associated tool call, when known. Omitted and `null` are equivalent. + """ + terminal_id: Annotated[Optional[str], Field(alias="terminalId")] = None + """ + The associated terminal, when already known. Omitted and `null` are equivalent. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. Omitted and `null` are equivalent and mean no subject metadata was provided. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + @field_validator("terminal_id", "tool_call_id", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class CreateFormElicitationRequestBase(BaseModel): + message: str + """ + A human-readable message describing what input is needed. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + mode: Literal["form"] = "form" + + +class CreateUrlElicitationRequestBase(BaseModel): + message: str + """ + A human-readable message describing what input is needed. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + mode: Literal["url"] = "url" + + +class ElicitationSessionScope(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The session this elicitation is tied to. + """ + tool_call_id: Annotated[Optional[str], Field(alias="toolCallId")] = None + """ + Optional tool call within the session. + + Optional. Omitted and `null` are equivalent and mean the elicitation is scoped to the + session without a specific tool call. + """ + + @field_validator("tool_call_id", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class ElicitationRequestScope(BaseModel): + request_id: Annotated[Optional[Union[int, str]], Field(alias="requestId")] + """ + The request this elicitation is tied to. + """ + + +class ElicitationOtherPropertySchema(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + type: str + """ + Custom or future elicitation property schema type. + + Values beginning with `_` are reserved for implementation-specific + extensions. Unknown values that do not begin with `_` are reserved for + future ACP variants. + """ + + +class EnumOption(BaseModel): + const: str + """ + The constant value for this option. + """ + title: str + """ + Human-readable title for this option. + """ + description: Optional[str] = None + """ + Human-readable description. + + Optional. Omitted and `null` are equivalent and mean no description is provided. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + @field_validator("description", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class StringPropertySchema(BaseModel): + title: Optional[str] = None + """ + Optional title for the property. + + Optional. Omitted and `null` are equivalent and mean no title is provided. + """ + description: Optional[str] = None + """ + Human-readable description. + + Optional. Omitted and `null` are equivalent and mean no description is provided. + """ + min_length: Annotated[Optional[int], Field(alias="minLength", ge=0)] = None + """ + Minimum string length. + + Optional. Omitted and `null` are equivalent and mean there is no minimum length constraint. + """ + max_length: Annotated[Optional[int], Field(alias="maxLength", ge=0)] = None + """ + Maximum string length. + + Optional. Omitted and `null` are equivalent and mean there is no maximum length constraint. + """ + pattern: Optional[str] = None + """ + Pattern the string must match. + + Optional. Omitted and `null` are equivalent and mean there is no pattern constraint. + """ + format: Optional[Union[Literal["email"], Literal["uri"], Literal["date"], Literal["date-time"], str]] = None + """ + String format. + + Optional. Omitted and `null` are equivalent and mean there is no format constraint. + """ + default: Optional[str] = None + """ + Default value. + + Optional. Omitted and `null` are equivalent and mean no default value is provided. + """ + enum: Annotated[Optional[List[str]], Field(min_length=1)] = None + """ + Enum values for untitled single-select enums. + Must contain at least one value when present. + Optional. Omitted and `null` are equivalent and mean no untitled single-select choices are + declared by `enum`. + """ + one_of: Annotated[Optional[List[EnumOption]], Field(alias="oneOf", min_length=1)] = None + """ + Titled enum options for titled single-select enums. + Must contain at least one option when present. + Optional. Omitted and `null` are equivalent and mean no titled single-select choices are + declared by `oneOf`. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + @field_validator("default", "description", "title", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class NumberPropertySchema(BaseModel): + title: Optional[str] = None + """ + Optional title for the property. + + Optional. Omitted and `null` are equivalent and mean no title is provided. + """ + description: Optional[str] = None + """ + Human-readable description. + + Optional. Omitted and `null` are equivalent and mean no description is provided. + """ + minimum: Optional[float] = None + """ + Minimum value (inclusive). + + Optional. Omitted and `null` are equivalent and mean there is no inclusive lower bound. + """ + maximum: Optional[float] = None + """ + Maximum value (inclusive). + + Optional. Omitted and `null` are equivalent and mean there is no inclusive upper bound. + """ + default: Optional[float] = None + """ + Default value. + + Optional. Omitted and `null` are equivalent and mean no default value is provided. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + @field_validator("default", "description", "title", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class IntegerPropertySchema(BaseModel): + title: Optional[str] = None + """ + Optional title for the property. + + Optional. Omitted and `null` are equivalent and mean no title is provided. + """ + description: Optional[str] = None + """ + Human-readable description. + + Optional. Omitted and `null` are equivalent and mean no description is provided. + """ + minimum: Optional[int] = None + """ + Minimum value (inclusive). + + Optional. Omitted and `null` are equivalent and mean there is no inclusive lower bound. + """ + maximum: Optional[int] = None + """ + Maximum value (inclusive). + + Optional. Omitted and `null` are equivalent and mean there is no inclusive upper bound. + """ + default: Optional[int] = None + """ + Default value. + + Optional. Omitted and `null` are equivalent and mean no default value is provided. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + @field_validator("default", "description", "title", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class BooleanPropertySchema(BaseModel): + title: Optional[str] = None + """ + Optional title for the property. + + Optional. Omitted and `null` are equivalent and mean no title is provided. + """ + description: Optional[str] = None + """ + Human-readable description. + + Optional. Omitted and `null` are equivalent and mean no description is provided. + """ + default: Optional[bool] = None + """ + Default value. + + Optional. Omitted and `null` are equivalent and mean no default value is provided. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + @field_validator("default", "description", "title", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class OtherMultiSelectItems(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + type: str + """ + Custom or future multi-select item type. + + Values beginning with `_` are reserved for implementation-specific + extensions. Unknown values that do not begin with `_` are reserved for + future ACP variants. + """ + + +class StringMultiSelectItemsBase(BaseModel): + enum: Annotated[List[str], Field(min_length=1)] + """ + Allowed enum values. Must contain at least one value. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + +class TitledMultiSelectItems(BaseModel): + any_of: Annotated[List[EnumOption], Field(alias="anyOf", min_length=1)] + """ + Titled enum options. Must contain at least one option. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + +class ElicitationUrlSessionMode(ElicitationSessionScope): + elicitation_id: Annotated[str, Field(alias="elicitationId")] + """ + The unique identifier for this elicitation. + """ + url: AnyUrl + """ + The URL to direct the user to. + """ + + +class ElicitationUrlRequestMode(ElicitationRequestScope): + elicitation_id: Annotated[str, Field(alias="elicitationId")] + """ + The unique identifier for this elicitation. + """ + url: AnyUrl + """ + The URL to direct the user to. + """ + + +class ElicitationUrlMode(RootModel[Union[ElicitationUrlSessionMode, ElicitationUrlRequestMode]]): + root: Union[ElicitationUrlSessionMode, ElicitationUrlRequestMode] + """ + URL-based elicitation mode where the client directs the user to a URL. + """ + + +class DisconnectMcpRequest(BaseModel): + connection_id: Annotated[str, Field(alias="connectionId")] + """ + The MCP-over-ACP connection to close. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class Implementation(BaseModel): + name: str + """ + Intended for programmatic or logical use, but can be used as a display + name fallback if title isn’t present. + """ + title: Optional[str] = None + """ + 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: str + """ + Version of the implementation. Can be displayed to the user or used + for debugging or metrics purposes. (e.g. "1.0.0"). + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("title", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class PromptImageCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class PromptAudioCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class PromptEmbeddedContextCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class McpStdioCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class McpHttpCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class McpAcpCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class SessionDeleteCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class SessionAdditionalDirectoriesCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class SessionForkCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class AgentAuthCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class ProvidersCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class NesDocumentDidOpenCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class NesDocumentDidCloseCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class NesDocumentDidSaveCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class NesDocumentDidFocusCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class NesRecentFilesCapabilities(BaseModel): + max_count: Annotated[Optional[int], Field(alias="maxCount", ge=0)] = None + """ + Maximum number of recent files the agent can use. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("max_count", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class NesRelatedSnippetsCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class NesEditHistoryCapabilities(BaseModel): + max_count: Annotated[Optional[int], Field(alias="maxCount", ge=0)] = None + """ + Maximum number of edit history entries the agent can use. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("max_count", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class NesUserActionsCapabilities(BaseModel): + max_count: Annotated[Optional[int], Field(alias="maxCount", ge=0)] = None + """ + Maximum number of user actions the agent can use. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("max_count", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class NesOpenFilesCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class NesDiagnosticsCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class EnvVariable(BaseModel): + name: str + """ + The name of the environment variable. + """ + value: str + """ + The value to set for the environment variable. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class AuthMethodTerminal(BaseModel): + method_id: Annotated[str, Field(alias="methodId")] + """ + Unique identifier for this authentication method. + """ + name: str + """ + Human-readable name of the authentication method. + """ + description: Optional[str] = None + """ + Optional description providing more details about this authentication method. + """ + args: Optional[List[str]] = None + """ + Additional arguments to append to the configured agent invocation for terminal auth. + """ + env: Optional[List[EnvVariable]] = None + """ + Additional environment variables to set on the configured agent invocation for terminal auth. + Names MUST be unique. These values override same-named variables in the + base launch configuration. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("description", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + @field_validator("args", "env", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class AuthMethodAgent(BaseModel): + method_id: Annotated[str, Field(alias="methodId")] + """ + Unique identifier for this authentication method. + """ + name: str + """ + Human-readable name of the authentication method. + """ + description: Optional[str] = None + """ + Optional description providing more details about this authentication method. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("description", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class LoginAuthResponse(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class ProviderCurrentConfig(BaseModel): + api_type: Annotated[ + Union[Literal["anthropic"], Literal["openai"], Literal["azure"], Literal["vertex"], Literal["bedrock"], str], + Field(alias="apiType"), + ] + """ + Protocol currently used by this provider. + """ + base_url: Annotated[AnyUrl, Field(alias="baseUrl")] + """ + Base URL currently used by this provider. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class SetProviderResponse(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class DisableProviderResponse(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class LogoutAuthResponse(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class SessionConfigSelectOption(BaseModel): + value: str + """ + Unique identifier for this option value. + """ + name: str + """ + Human-readable label for this option value. + """ + description: Optional[str] = None + """ + Optional description for this option value. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("description", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class SessionConfigBoolean(BaseModel): + current_value: Annotated[bool, Field(alias="currentValue")] + """ + The current value of the boolean option. + """ + + +class SessionInfo(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + Unique identifier for the session + """ + cwd: str + """ + The working directory for this session. Must be an absolute path. + """ + additional_directories: Annotated[Optional[List[str]], Field(alias="additionalDirectories")] = None + """ + Additional workspace roots reported for this session. Each path must be absolute. + + When present, this is the complete ordered additional-root list reported + by the Agent. Omitted and empty values are equivalent: the response + reports no additional roots. + """ + title: Optional[str] = None + """ + Human-readable title for the session + """ + updated_at: Annotated[Optional[AwareDatetime], Field(alias="updatedAt")] = None + """ + RFC 3339 timestamp of last activity. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("title", "updated_at", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + @field_validator("additional_directories", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class DeleteSessionResponse(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class CloseSessionResponse(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class PromptResponse(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class StartNesResponse(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The session ID for the newly started NES session. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class Position(BaseModel): + line: Annotated[int, Field(ge=0)] + """ + Zero-based line number. + """ + character: Annotated[int, Field(ge=0)] + """ + Zero-based character offset (encoding-dependent). + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class NesJumpSuggestion(BaseModel): + suggestion_id: Annotated[str, Field(alias="suggestionId")] + """ + Unique identifier for accept/reject tracking. + """ + uri: AnyUrl + """ + The file to navigate to. + """ + position: Position + """ + The target position within the file. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class NesRenameSuggestion(BaseModel): + suggestion_id: Annotated[str, Field(alias="suggestionId")] + """ + Unique identifier for accept/reject tracking. + """ + uri: AnyUrl + """ + The file URI containing the symbol. + """ + position: Position + """ + The position of the symbol to rename. + """ + new_name: Annotated[str, Field(alias="newName")] + """ + The new name for the symbol. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class NesSearchAndReplaceSuggestion(BaseModel): + suggestion_id: Annotated[str, Field(alias="suggestionId")] + """ + Unique identifier for accept/reject tracking. + """ + uri: AnyUrl + """ + The file URI to search within. + """ + search: str + """ + The text or pattern to find. + """ + replace: str + """ + The replacement text. + """ + is_regex: Annotated[Optional[bool], Field(alias="isRegex")] = None + """ + Whether `search` is a regular expression. Defaults to `false`. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class CloseNesResponse(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class OtherSessionStateUpdateBase(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + state: str + """ + Custom or future session state. + + Values beginning with `_` are reserved for implementation-specific + extensions. Unknown values that do not begin with `_` are reserved for + future ACP variants. + """ + + +class SessionStateUpdateBase(BaseModel): + session_update: Annotated[Literal["state_update"], Field(alias="sessionUpdate")] = "state_update" + + +class OtherSessionStateUpdate(OtherSessionStateUpdateBase, SessionStateUpdateBase): + session_update: Annotated[Literal["state_update"], Field(alias="sessionUpdate")] = "state_update" + + +class OtherSessionUpdate(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + session_update: Annotated[str, Field(alias="sessionUpdate")] + """ + Custom or future session update type. + + Values beginning with `_` are reserved for implementation-specific + extensions. Unknown values that do not begin with `_` are reserved for + future ACP variants. + """ + + +class RunningStateUpdate(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class Usage(BaseModel): + total_tokens: Annotated[int, Field(alias="totalTokens", ge=0)] + """ + Sum of all token types across session. + """ + input_tokens: Annotated[int, Field(alias="inputTokens", ge=0)] + """ + Total input tokens. + """ + output_tokens: Annotated[int, Field(alias="outputTokens", ge=0)] + """ + Total output tokens. + """ + thought_tokens: Annotated[Optional[int], Field(alias="thoughtTokens", ge=0)] = None + """ + Total thought/reasoning tokens + """ + cached_read_tokens: Annotated[Optional[int], Field(alias="cachedReadTokens", ge=0)] = None + """ + Total cache read tokens. + """ + cached_write_tokens: Annotated[Optional[int], Field(alias="cachedWriteTokens", ge=0)] = None + """ + Total cache write tokens. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("cached_read_tokens", "cached_write_tokens", "thought_tokens", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class IdleStateUpdate(BaseModel): + stop_reason: Annotated[ + Optional[ + Union[ + Literal["end_turn"], + Literal["max_tokens"], + Literal["max_turn_requests"], + Literal["refusal"], + Literal["cancelled"], + str, + ] + ], + Field(alias="stopReason"), + ] = None + """ + Indicates why foreground work stopped. + + Optional. Omitted or `null` both mean the agent is not reporting a stop reason. + Agents SHOULD include this when the idle transition ends foreground work. + """ + usage: Optional[Usage] = None + """ + **UNSTABLE** + + This capability is not part of the spec yet, and may be removed or changed at any point. + + Token usage for completed foreground work. + + Optional. Omitted or `null` both mean the agent is not reporting token + usage for this state update. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("stop_reason", "usage", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class RequiresActionStateUpdate(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class RunningState(RunningStateUpdate): + state: Literal["running"] = "running" + + +class IdleState(IdleStateUpdate): + state: Literal["idle"] = "idle" + + +class RequiresActionState(RequiresActionStateUpdate): + state: Literal["requires_action"] = "requires_action" + + +class OtherState(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + state: str + """ + Custom or future session state. + + Values beginning with `_` are reserved for implementation-specific + extensions. Unknown values that do not begin with `_` are reserved for + future ACP variants. + """ + + +class StateUpdate(RootModel[Union[RunningState, IdleState, RequiresActionState, OtherState]]): + root: Union[RunningState, IdleState, RequiresActionState, OtherState] + """ + The state of the agent's foreground work has changed. + + Background activity can continue and emit other `session/update` notifications + while `idle`. Those notifications do not change this state. + """ + + +class TerminalOutput(BaseModel): + data: Annotated[str, Field(json_schema_extra={"contentEncoding": "base64"})] + """ + Base64-encoded replacement terminal output bytes. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. This metadata is scoped to the replacement snapshot. Omitted + and `null` are equivalent and mean no snapshot metadata was provided. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + +class TerminalExitStatus(BaseModel): + exit_code: Annotated[Optional[int], Field(alias="exitCode", ge=0)] = None + """ + Process exit code, when known. Omitted and `null` are equivalent. + """ + signal: Optional[str] = None + """ + Signal that terminated the process, when known. + + Agents should use the conventional platform signal name. POSIX examples + include `SIGTERM`, `SIGKILL`, and `SIGINT`. Other platforms may use a + platform-specific name. Omitted and `null` are equivalent. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. This metadata is scoped to the exit information. Omitted + and `null` are equivalent and mean no exit metadata was provided. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + @field_validator("exit_code", "signal", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class TerminalUpdate(BaseModel): + terminal_id: Annotated[str, Field(alias="terminalId")] + """ + Unique identifier for this terminal within the session. + """ + command: Optional[str] = None + """ + The command being run. + """ + cwd: Optional[str] = None + """ + The absolute working directory of the command. + """ + output: Optional[TerminalOutput] = None + """ + An authoritative replacement snapshot of terminal output bytes. + """ + exit_status: Annotated[Optional[TerminalExitStatus], Field(alias="exitStatus")] = None + """ + Exit information. A concrete object marks the terminal as exited. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + The _meta property is reserved by ACP to allow clients and agents to attach additional + metadata to their interactions. Omitted means no metadata update; `null` is an + explicit clear signal. Implementations MUST NOT make assumptions about values at these keys. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + @field_validator("command", "cwd", "exit_status", "output", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class TerminalOutputChunk(BaseModel): + terminal_id: Annotated[str, Field(alias="terminalId")] + """ + The terminal receiving these bytes. + """ + data: Annotated[str, Field(json_schema_extra={"contentEncoding": "base64"})] + """ + Independently base64-encoded terminal output bytes. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. This field is chunk-scoped. Omitted and `null` are + equivalent and mean no chunk metadata was provided. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + +class PlanFile(BaseModel): + plan_id: Annotated[str, Field(alias="planId")] + """ + The plan ID to update. + """ + uri: AnyUrl + """ + The URI of the file containing the plan. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class PlanMarkdown(BaseModel): + plan_id: Annotated[str, Field(alias="planId")] + """ + The plan ID to update. + """ + content: str + """ + Markdown content for the plan. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class PlanRemoved(BaseModel): + plan_id: Annotated[str, Field(alias="planId")] + """ + The plan ID to remove. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class OtherAvailableCommandInput(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + type: str + """ + Custom or future command input type. + + Values beginning with `_` are reserved for implementation-specific + extensions. Unknown values that do not begin with `_` are reserved for + future ACP variants. + """ + + +class TextCommandInput(BaseModel): + hint: str + """ + A hint to display when the input hasn't been provided yet + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class SessionInfoUpdateBase(BaseModel): + title: Optional[str] = None + """ + Human-readable title for the session. Set to null to clear. + """ + updated_at: Annotated[Optional[AwareDatetime], Field(alias="updatedAt")] = None + """ + RFC 3339 timestamp of last activity. Set to null to clear. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + The _meta property is reserved by ACP to allow clients and agents to attach additional + metadata to their interactions. Omitted means no metadata update; `null` is an + explicit clear signal. Implementations MUST NOT make assumptions about values at these keys. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + +class Cost(BaseModel): + amount: float + """ + Total cumulative cost for session. + """ + currency: Annotated[str, Field(pattern="^[A-Z]{3}$")] + """ + ISO 4217 currency code (e.g., "USD", "EUR"). + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class UsageUpdateBase(BaseModel): + used: Annotated[int, Field(ge=0)] + """ + Tokens currently in context. + """ + size: Annotated[int, Field(ge=0)] + """ + Total context window size in tokens. + """ + cost: Optional[Cost] = None + """ + Cumulative session cost (optional). + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class CompleteElicitationNotification(BaseModel): + elicitation_id: Annotated[str, Field(alias="elicitationId")] + """ + The ID of the elicitation that completed. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + +class MessageMcpNotification(BaseModel): + connection_id: Annotated[str, Field(alias="connectionId")] + """ + The MCP-over-ACP connection this message is sent on. + """ + method: str + """ + The inner MCP method name. + """ + params: Optional[Dict[str, Any]] = None + """ + Optional inner MCP params. + + If omitted or set to `null`, the inner MCP message has no params. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("params", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class TerminalAuthCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class ElicitationFormCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + +class ElicitationUrlCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + +class NesJumpCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class NesRenameCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class NesSearchAndReplaceCapabilities(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class LoginAuthRequest(BaseModel): + method_id: Annotated[str, Field(alias="methodId")] + """ + The ID of the authentication method to use. + Must be one of the methods advertised in the initialize response. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class ListProvidersRequest(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class SetProviderRequest(BaseModel): + provider_id: Annotated[str, Field(alias="providerId")] + """ + Provider ID to configure. + """ + api_type: Annotated[ + Union[Literal["anthropic"], Literal["openai"], Literal["azure"], Literal["vertex"], Literal["bedrock"], str], + Field(alias="apiType"), + ] + """ + Protocol type for this provider. + """ + base_url: Annotated[AnyUrl, Field(alias="baseUrl")] + """ + Base URL for requests sent through this provider. + """ + headers: Optional[Dict[str, str]] = None + """ + Full headers map for this provider. + May include authorization, routing, or other integration-specific headers. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class DisableProviderRequest(BaseModel): + provider_id: Annotated[str, Field(alias="providerId")] + """ + Provider ID to disable. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class LogoutAuthRequest(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class OtherMcpServer(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + type: str + """ + Custom or future MCP server transport type. + + Values beginning with `_` are reserved for implementation-specific + extensions. Unknown values that do not begin with `_` are reserved for + future ACP variants. + """ + + +class HttpHeader(BaseModel): + name: str + """ + The name of the HTTP header. + """ + value: str + """ + The value to set for the HTTP header. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class McpServerHttp(BaseModel): + name: str + """ + Human-readable name identifying this MCP server. + """ + url: AnyUrl + """ + URL to the MCP server. + """ + headers: Optional[List[HttpHeader]] = None + """ + HTTP headers to set when making requests to the MCP server. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class McpServerAcp(BaseModel): + name: str + """ + Human-readable name identifying this MCP server. + """ + server_id: Annotated[str, Field(alias="serverId")] + """ + Unique identifier for this MCP server, generated by the component providing it. + + Providers MUST NOT reuse an ID for multiple ACP-transport MCP servers that are visible + on the same ACP connection. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class McpServerStdio(BaseModel): + name: str + """ + Human-readable name identifying this MCP server. + """ + command: str + """ + Absolute path to the MCP server executable. + """ + args: Optional[List[str]] = None + """ + Command-line arguments to pass to the MCP server. + """ + env: Optional[List[EnvVariable]] = None + """ + Environment variables to set when launching the MCP server. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class ListSessionsRequest(BaseModel): + cwd: Optional[str] = None + """ + Filter sessions by working directory. Must be an absolute path. + """ + cursor: Optional[str] = None + """ + Opaque cursor token from a previous response's nextCursor field for cursor-based pagination + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class DeleteSessionRequest(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The ID of the session to delete. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class OtherReplayFrom(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + type: str + """ + Custom or future replay cursor type. + + Values beginning with `_` are reserved for implementation-specific + extensions. Unknown values that do not begin with `_` are reserved for + future ACP variants. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class ReplayFromStart(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class CloseSessionRequest(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The ID of the session to close. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class SetSessionConfigOptionIdRequest(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The ID of the session to set the configuration option for. + """ + config_id: Annotated[str, Field(alias="configId")] + """ + The ID of the configuration option to set. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + value: str + """ + The value ID. + """ + type: Literal["id"] = "id" + + +class SetSessionConfigOptionBooleanRequest(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The ID of the session to set the configuration option for. + """ + config_id: Annotated[str, Field(alias="configId")] + """ + The ID of the configuration option to set. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + value: bool + """ + The boolean value. + """ + type: Literal["boolean"] = "boolean" + + +class SetSessionConfigOptionOtherRequest(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + session_id: Annotated[str, Field(alias="sessionId")] + """ + The ID of the session to set the configuration option for. + """ + config_id: Annotated[str, Field(alias="configId")] + """ + The ID of the configuration option to set. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + type: str + """ + Custom or future session configuration option value type. + + Values beginning with `_` are reserved for implementation-specific + extensions. Unknown values that do not begin with `_` are reserved for + future ACP variants. + """ + value: Any + """ + Raw value payload for the custom or future value type. + """ + + +class WorkspaceFolder(BaseModel): + uri: AnyUrl + """ + The URI of the folder. + """ + name: str + """ + The display name of the folder. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class NesRepository(BaseModel): + name: str + """ + The repository name. + """ + owner: str + """ + The repository owner. + """ + remote_url: Annotated[str, Field(alias="remoteUrl")] + """ + The remote URL of the repository. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class NesRecentFile(BaseModel): + uri: AnyUrl + """ + The URI of the file. + """ + language_id: Annotated[str, Field(alias="languageId")] + """ + The language identifier. + """ + text: str + """ + The full text content of the file. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class NesExcerpt(BaseModel): + start_line: Annotated[int, Field(alias="startLine", ge=0)] + """ + The start line of the excerpt (zero-based). + """ + end_line: Annotated[int, Field(alias="endLine", ge=0)] + """ + The end line of the excerpt (zero-based). + """ + text: str + """ + The text content of the excerpt. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class NesEditHistoryEntry(BaseModel): + uri: AnyUrl + """ + The URI of the edited file. + """ + diff: str + """ + A diff representing the edit. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class NesUserAction(BaseModel): + action: str + """ + The kind of action (e.g., "insertChar", "cursorMovement"). + """ + uri: AnyUrl + """ + The URI of the file where the action occurred. + """ + position: Position + """ + The position where the action occurred. + """ + timestamp_ms: Annotated[int, Field(alias="timestampMs", ge=0)] + """ + Timestamp in milliseconds since epoch. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class CloseNesRequest(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The ID of the NES session to close. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class CancelledPermissionOutcome(BaseModel): + outcome: Literal["cancelled"] = "cancelled" + + +class OtherPermissionOutcome(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + outcome: str + """ + Custom or future permission outcome. + + Values beginning with `_` are reserved for implementation-specific + extensions. Unknown values that do not begin with `_` are reserved for + future ACP variants. + """ + + +class SelectedPermissionOutcome(BaseModel): + option_id: Annotated[str, Field(alias="optionId")] + """ + The ID of the option the user selected. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class DeclineElicitationResponse(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + action: Literal["decline"] = "decline" + + +class CancelElicitationResponse(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + action: Literal["cancel"] = "cancel" + + +class OtherElicitationResponse(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + action: str + """ + Custom or future elicitation action. + + Values beginning with `_` are reserved for implementation-specific + extensions. Unknown values that do not begin with `_` are reserved for + future ACP variants. + """ + + +class ElicitationContentValue(RootModel[Union[str, int, float, bool, List[str]]]): + root: Union[str, int, float, bool, List[str]] + """ + Allowed wire representations for [`ElicitationContentValue`]. + """ + + +class ElicitationAcceptAction(BaseModel): + content: Optional[Dict[str, Any]] = None + """ + The user-provided content, if any, as an object matching the requested schema. + """ + + +class ConnectMcpResponse(BaseModel): + connection_id: Annotated[str, Field(alias="connectionId")] + """ + The unique identifier for this MCP-over-ACP connection. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class DisconnectMcpResponse(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class CancelSessionNotification(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The ID of the session to cancel operations for. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class DidOpenDocumentNotification(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The session ID for this notification. + """ + uri: AnyUrl + """ + The URI of the opened document. + """ + language_id: Annotated[str, Field(alias="languageId")] + """ + The language identifier of the document (e.g., "rust", "python"). + """ + version: int + """ + The version number of the document. + """ + text: str + """ + The full text content of the document. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class DidCloseDocumentNotification(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The session ID for this notification. + """ + uri: AnyUrl + """ + The URI of the closed document. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class DidSaveDocumentNotification(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The session ID for this notification. + """ + uri: AnyUrl + """ + The URI of the saved document. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class AcceptNesNotification(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The session ID for this notification. + """ + suggestion_id: Annotated[str, Field(alias="suggestionId")] + """ + The ID of the accepted suggestion. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class CancelRequestNotification(BaseModel): + request_id: Annotated[Optional[Union[int, str]], Field(alias="requestId")] + """ + The ID of the request to cancel. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class CommandPermissionSubjectVariant(CommandPermissionSubject): + type: Literal["command"] = "command" + + +class TerminalToolCallContent(Terminal): + type: Literal["terminal"] = "terminal" + + +class Annotations(BaseModel): + audience: Optional[List[Union[Literal["assistant"], Literal["user"], str]]] = None + """ + Intended recipients for this content, such as the user or assistant. + """ + last_modified: Annotated[Optional[AwareDatetime], Field(alias="lastModified")] = None + """ + Timestamp indicating when the underlying resource was last modified. + + Must be an RFC 3339 formatted string (e.g., "2025-01-12T15:00:58Z"). + """ + priority: Annotated[Optional[float], Field(ge=0.0, le=1.0)] = None + """ + Relative importance of this content when clients choose what to surface. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("last_modified", "priority", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + @field_validator("audience", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class TextContent(BaseModel): + text: str + """ + Text payload carried by this content block. + """ + annotations: Optional[Annotations] = None + """ + Optional annotations that help clients decide how to display or route this content. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("annotations", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class ImageContent(BaseModel): + data: Annotated[str, Field(json_schema_extra={"contentEncoding": "base64"})] + """ + Base64-encoded media payload. + """ + mime_type: Annotated[str, Field(alias="mimeType")] + """ + MIME type describing the encoded media payload. + """ + uri: Optional[AnyUrl] = None + """ + URI associated with this resource or media payload. + """ + annotations: Optional[Annotations] = None + """ + Optional annotations that help clients decide how to display or route this content. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("annotations", "uri", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class AudioContent(BaseModel): + data: Annotated[str, Field(json_schema_extra={"contentEncoding": "base64"})] + """ + Base64-encoded media payload. + """ + mime_type: Annotated[str, Field(alias="mimeType")] + """ + MIME type describing the encoded media payload. + """ + annotations: Optional[Annotations] = None + """ + Optional annotations that help clients decide how to display or route this content. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("annotations", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class Icon(BaseModel): + src: AnyUrl + """ + A standard URI pointing to an icon resource. + """ + mime_type: Annotated[Optional[str], Field(alias="mimeType")] = None + """ + Optional MIME type override if the source MIME type is missing or generic. + """ + sizes: Optional[List[str]] = None + """ + Optional array of strings that specify sizes at which the icon can be used. + Each string should be in `WxH` format (e.g., `"48x48"`, `"96x96"`) or + `"any"` for scalable formats like SVG. + + If not provided, the client should assume that the icon can be used at any size. + """ + theme: Optional[Union[Literal["light"], Literal["dark"], str]] = None + """ + Optional theme this icon is designed for. + """ + + @field_validator("mime_type", "theme", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + @field_validator("sizes", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class ResourceLink(BaseModel): + name: str + """ + Human-readable name shown for this protocol object. + """ + uri: AnyUrl + """ + URI associated with this resource or media payload. + """ + title: Optional[str] = None + """ + Optional display title for end-user UI. + """ + description: Optional[str] = None + """ + Optional human-readable details shown with this protocol object. + """ + icons: Optional[List[Icon]] = None + """ + Optional set of sized icons that the client can display in a user interface. + """ + mime_type: Annotated[Optional[str], Field(alias="mimeType")] = None + """ + MIME type describing the encoded media payload. + """ + size: Optional[int] = None + """ + Optional size of the linked resource in bytes, if known. + """ + annotations: Optional[Annotations] = None + """ + Optional annotations that help clients decide how to display or route this content. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("annotations", "description", "mime_type", "size", "title", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + @field_validator("icons", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class EmbeddedResource(BaseModel): + resource: Union[TextResourceContents, BlobResourceContents] + """ + Embedded resource payload, either text or binary data. + """ + annotations: Optional[Annotations] = None + """ + Optional annotations that help clients decide how to display or route this content. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("annotations", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class AddDiffChange(DiffPathChange): + file_type: Annotated[ + Optional[Union[Literal["text"], Literal["binary"], Literal["directory"], Literal["symlink"], str]], + Field(alias="fileType"), + ] = None + """ + File content kind. + + Omitted or `null` means the content kind is unknown. + """ + mime_type: Annotated[Optional[str], Field(alias="mimeType")] = None + """ + MIME type of the file contents. + + Omitted or `null` means the MIME type is unknown. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + operation: Literal["add"] = "add" + + +class DeleteDiffChange(DiffPathChange): + file_type: Annotated[ + Optional[Union[Literal["text"], Literal["binary"], Literal["directory"], Literal["symlink"], str]], + Field(alias="fileType"), + ] = None + """ + File content kind. + + Omitted or `null` means the content kind is unknown. + """ + mime_type: Annotated[Optional[str], Field(alias="mimeType")] = None + """ + MIME type of the file contents. + + Omitted or `null` means the MIME type is unknown. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + operation: Literal["delete"] = "delete" + + +class ModifyDiffChange(DiffPathChange): + file_type: Annotated[ + Optional[Union[Literal["text"], Literal["binary"], Literal["directory"], Literal["symlink"], str]], + Field(alias="fileType"), + ] = None + """ + File content kind. + + Omitted or `null` means the content kind is unknown. + """ + mime_type: Annotated[Optional[str], Field(alias="mimeType")] = None + """ + MIME type of the file contents. + + Omitted or `null` means the MIME type is unknown. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + operation: Literal["modify"] = "modify" + + +class MoveDiffChange(DiffPathPairChange): + file_type: Annotated[ + Optional[Union[Literal["text"], Literal["binary"], Literal["directory"], Literal["symlink"], str]], + Field(alias="fileType"), + ] = None + """ + File content kind. + + Omitted or `null` means the content kind is unknown. + """ + mime_type: Annotated[Optional[str], Field(alias="mimeType")] = None + """ + MIME type of the file contents. + + Omitted or `null` means the MIME type is unknown. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + operation: Literal["move"] = "move" + + +class CopyDiffChange(DiffPathPairChange): + file_type: Annotated[ + Optional[Union[Literal["text"], Literal["binary"], Literal["directory"], Literal["symlink"], str]], + Field(alias="fileType"), + ] = None + """ + File content kind. + + Omitted or `null` means the content kind is unknown. + """ + mime_type: Annotated[Optional[str], Field(alias="mimeType")] = None + """ + MIME type of the file contents. + + Omitted or `null` means the MIME type is unknown. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + operation: Literal["copy"] = "copy" + + +class OtherDiffChange(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + file_type: Annotated[ + Optional[Union[Literal["text"], Literal["binary"], Literal["directory"], Literal["symlink"], str]], + Field(alias="fileType"), + ] = None + """ + File content kind. + + Omitted or `null` means the content kind is unknown. + """ + mime_type: Annotated[Optional[str], Field(alias="mimeType")] = None + """ + MIME type of the file contents. + + Omitted or `null` means the MIME type is unknown. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + operation: str + """ + Custom or future file operation. + + Values beginning with `_` are reserved for implementation-specific + extensions. Unknown values that do not begin with `_` are reserved for + future ACP variants. + """ + + +class DiffPatch(BaseModel): + format: Union[Literal["git_patch"], str] + """ + Patch format. The only ACP-defined value is `git_patch`. + """ + text: str + """ + Patch text in the format named by `format`. + """ + + +class Diff(BaseModel): + changes: List[ + Union[AddDiffChange, DeleteDiffChange, ModifyDiffChange, MoveDiffChange, CopyDiffChange, OtherDiffChange] + ] + """ + Structured file changes described by this diff. + + Clients can use this field without parsing patch text to determine affected paths. + """ + patch: Optional[DiffPatch] = None + """ + Renderable patch text for some or all of the structured changes. + + Agents SHOULD provide patch text whenever feasible. Omitted or `null` + means no renderable patch text was provided. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("patch", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + @field_validator("changes", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class PermissionOption(BaseModel): + option_id: Annotated[str, Field(alias="optionId")] + """ + Unique identifier for this permission option. + """ + name: str + """ + Human-readable label to display to the user. + """ + kind: Union[Literal["allow_once"], Literal["allow_always"], Literal["reject_once"], Literal["reject_always"], str] + """ + Hint about the nature of this permission option. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class CreateUrlSessionElicitationRequestBase(ElicitationSessionScope): + elicitation_id: Annotated[str, Field(alias="elicitationId")] + """ + The unique identifier for this elicitation. + """ + url: AnyUrl + """ + The URL to direct the user to. + """ + + +class CreateUrlRequestElicitationRequestBase(ElicitationRequestScope): + elicitation_id: Annotated[str, Field(alias="elicitationId")] + """ + The unique identifier for this elicitation. + """ + url: AnyUrl + """ + The URL to direct the user to. + """ + + +class CreateUrlSessionElicitationRequest(CreateUrlSessionElicitationRequestBase, CreateUrlElicitationRequestBase): + message: str + """ + A human-readable message describing what input is needed. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + mode: Literal["url"] = "url" + + +class CreateUrlRequestElicitationRequest(CreateUrlRequestElicitationRequestBase, CreateUrlElicitationRequestBase): + message: str + """ + A human-readable message describing what input is needed. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + mode: Literal["url"] = "url" + + +class CreateOtherSessionElicitationRequest(ElicitationSessionScope): + model_config = ConfigDict( + extra="allow", + ) + message: str + """ + A human-readable message describing what input is needed. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + mode: str + """ + Custom or future elicitation mode. + + Values beginning with `_` are reserved for implementation-specific + extensions. Unknown values that do not begin with `_` are reserved for + future ACP variants. + """ + + +class CreateOtherRequestElicitationRequest(ElicitationRequestScope): + model_config = ConfigDict( + extra="allow", + ) + message: str + """ + A human-readable message describing what input is needed. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + mode: str + """ + Custom or future elicitation mode. + + Values beginning with `_` are reserved for implementation-specific + extensions. Unknown values that do not begin with `_` are reserved for + future ACP variants. + """ + + +class ElicitationStringPropertySchema(StringPropertySchema): + type: Literal["string"] = "string" + + +class ElicitationNumberPropertySchema(NumberPropertySchema): + type: Literal["number"] = "number" + + +class ElicitationIntegerPropertySchema(IntegerPropertySchema): + type: Literal["integer"] = "integer" + + +class ElicitationBooleanPropertySchema(BooleanPropertySchema): + type: Literal["boolean"] = "boolean" + + +class StringMultiSelectItems(StringMultiSelectItemsBase): + type: Literal["string"] = "string" + + +class MultiSelectPropertySchema(BaseModel): + title: Optional[str] = None + """ + Optional title for the property. + + Optional. Omitted and `null` are equivalent and mean no title is provided. + """ + description: Optional[str] = None + """ + Human-readable description. + + Optional. Omitted and `null` are equivalent and mean no description is provided. + """ + min_items: Annotated[Optional[int], Field(alias="minItems", ge=0)] = None + """ + Minimum number of items to select. + + Optional. Omitted and `null` are equivalent and mean there is no minimum selection count. + """ + max_items: Annotated[Optional[int], Field(alias="maxItems", ge=0)] = None + """ + Maximum number of items to select. + + Optional. Omitted and `null` are equivalent and mean there is no maximum selection count. + """ + items: Union[StringMultiSelectItems, OtherMultiSelectItems, TitledMultiSelectItems] + """ + The items definition describing allowed values. + """ + default: Optional[List[str]] = None + """ + Default selected values. + + Optional. Omitted and `null` are equivalent and mean no default selections are provided. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + @field_validator("description", "title", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + @field_validator("default", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class ConnectMcpRequest(BaseModel): + server_id: Annotated[str, Field(alias="serverId")] + """ + The ACP MCP server ID that was provided by the component declaring the MCP server. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class MessageMcpRequest(BaseModel): + connection_id: Annotated[str, Field(alias="connectionId")] + """ + The MCP-over-ACP connection this message is sent on. + """ + method: str + """ + The inner MCP method name. + """ + params: Optional[Dict[str, Any]] = None + """ + Optional inner MCP params. + + If omitted or set to `null`, the inner MCP message has no params. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class PromptCapabilities(BaseModel): + image: Optional[PromptImageCapabilities] = None + """ + Agent supports [`ContentBlock::Image`]. + + Optional. Omitted or `null` both mean the agent does not advertise support. + Supplying `{}` means the agent supports image content in prompts. + """ + audio: Optional[PromptAudioCapabilities] = None + """ + Agent supports [`ContentBlock::Audio`]. + + Optional. Omitted or `null` both mean the agent does not advertise support. + Supplying `{}` means the agent supports audio content in prompts. + """ + embedded_context: Annotated[Optional[PromptEmbeddedContextCapabilities], Field(alias="embeddedContext")] = None + """ + Agent supports embedded context in `session/prompt` requests. + + When enabled, the Client is allowed to include [`ContentBlock::Resource`] + in prompt requests for pieces of context that are referenced in the message. + + Optional. Omitted or `null` both mean the agent does not advertise support. + Supplying `{}` means the agent supports embedded context in prompts. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("audio", "embedded_context", "image", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class McpCapabilities(BaseModel): + stdio: Optional[McpStdioCapabilities] = None + """ + Agent supports [`McpServer::Stdio`]. + + Optional. Omitted or `null` both mean the agent does not advertise support. + Supplying `{}` means the agent supports stdio MCP server transports. + """ + http: Optional[McpHttpCapabilities] = None + """ + Agent supports [`McpServer::Http`]. + + Optional. Omitted or `null` both mean the agent does not advertise support. + Supplying `{}` means the agent supports HTTP MCP server transports. + """ + acp: Optional[McpAcpCapabilities] = None + """ + **UNSTABLE** + + This capability is not part of the spec yet, and may be removed or changed at any point. + + Agent supports [`McpServer::Acp`]. + + Optional. Omitted or `null` both mean the agent does not advertise support. + Supplying `{}` means the agent supports ACP MCP server transports. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("acp", "http", "stdio", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class NesDocumentDidChangeCapabilities(BaseModel): + sync_kind: Annotated[Literal["full", "incremental"], Field(alias="syncKind")] + """ + The sync kind the agent wants: `"full"` or `"incremental"`. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class NesContextCapabilities(BaseModel): + recent_files: Annotated[Optional[NesRecentFilesCapabilities], Field(alias="recentFiles")] = None + """ + Whether the agent wants recent files context. + """ + related_snippets: Annotated[Optional[NesRelatedSnippetsCapabilities], Field(alias="relatedSnippets")] = None + """ + Whether the agent wants related snippets context. + """ + edit_history: Annotated[Optional[NesEditHistoryCapabilities], Field(alias="editHistory")] = None + """ + Whether the agent wants edit history context. + """ + user_actions: Annotated[Optional[NesUserActionsCapabilities], Field(alias="userActions")] = None + """ + Whether the agent wants user actions context. + """ + open_files: Annotated[Optional[NesOpenFilesCapabilities], Field(alias="openFiles")] = None + """ + Whether the agent wants open files context. + """ + diagnostics: Optional[NesDiagnosticsCapabilities] = None + """ + Whether the agent wants diagnostics context. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator( + "diagnostics", "edit_history", "open_files", "recent_files", "related_snippets", "user_actions", mode="wrap" + ) + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class TerminalAuthMethod(AuthMethodTerminal): + type: Literal["terminal"] = "terminal" + + +class AgentAuthMethod(AuthMethodAgent): + type: Literal["agent"] = "agent" + + +class OtherAuthMethod(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + type: str + """ + Custom or future authentication method type. + + Values beginning with `_` are reserved for implementation-specific + extensions. Unknown values that do not begin with `_` are reserved for + future ACP variants. + """ + method_id: Annotated[str, Field(alias="methodId")] + """ + Unique identifier for this authentication method. + """ + name: str + """ + Human-readable name of the authentication method. + """ + description: Optional[str] = None + """ + Optional description providing more details about this authentication method. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class ProviderInfo(BaseModel): + provider_id: Annotated[str, Field(alias="providerId")] + """ + Provider identifier, for example "main" or "openai". + """ + supported: List[ + Union[Literal["anthropic"], Literal["openai"], Literal["azure"], Literal["vertex"], Literal["bedrock"], str] + ] + """ + Supported protocol types for this provider. + """ + required: bool + """ + Whether this provider is mandatory and cannot be disabled via `providers/disable`. + If true, clients must not call `providers/disable` for this provider ID. + """ + current: Optional[ProviderCurrentConfig] = None + """ + Current effective non-secret routing config. + Null or omitted means provider is disabled. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("supported", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class BooleanSessionConfigOption(SessionConfigBoolean): + config_id: Annotated[str, Field(alias="configId")] + """ + Unique identifier for the configuration option. + """ + name: str + """ + Human-readable label for the option. + """ + description: Optional[str] = None + """ + Optional description for the Client to display to the user. + """ + category: Optional[ + Union[Literal["mode"], Literal["model"], Literal["model_config"], Literal["thought_level"], str] + ] = None + """ + Optional semantic category for this option (UX only). + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + type: Literal["boolean"] = "boolean" + + +class OtherSessionConfigOption(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + config_id: Annotated[str, Field(alias="configId")] + """ + Unique identifier for the configuration option. + """ + name: str + """ + Human-readable label for the option. + """ + description: Optional[str] = None + """ + Optional description for the Client to display to the user. + """ + category: Optional[ + Union[Literal["mode"], Literal["model"], Literal["model_config"], Literal["thought_level"], str] + ] = None + """ + Optional semantic category for this option (UX only). + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + type: str + """ + Custom or future session configuration option type. + + Values beginning with `_` are reserved for implementation-specific + extensions. Unknown values that do not begin with `_` are reserved for + future ACP variants. + """ + + +class SessionConfigSelectGroup(BaseModel): + group_id: Annotated[str, Field(alias="groupId")] + """ + Unique identifier for this group. + """ + name: str + """ + Human-readable label for this group. + """ + options: List[SessionConfigSelectOption] + """ + The set of option values in this group. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("options", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class ListSessionsResponse(BaseModel): + sessions: List[SessionInfo] + """ + Array of session information objects. + """ + next_cursor: Annotated[Optional[str], Field(alias="nextCursor")] = None + """ + 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. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("next_cursor", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + @field_validator("sessions", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class NesJumpSuggestionVariant(NesJumpSuggestion): + kind: Literal["jump"] = "jump" + + +class NesRenameSuggestionVariant(NesRenameSuggestion): + kind: Literal["rename"] = "rename" + + +class NesSearchAndReplaceSuggestionVariant(NesSearchAndReplaceSuggestion): + kind: Literal["searchAndReplace"] = "searchAndReplace" + + +class OtherNesSuggestion(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + kind: str + """ + Custom or future NES suggestion kind. + + Values beginning with `_` are reserved for implementation-specific + extensions. Unknown values that do not begin with `_` are reserved for + future ACP variants. + """ + suggestion_id: Annotated[str, Field(alias="suggestionId")] + """ + Unique identifier for accept/reject tracking. + """ + + +class Range(BaseModel): + start: Position + """ + The start position (inclusive). + """ + end: Position + """ + The end position (exclusive). + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class Error(BaseModel): + code: Union[ + Literal[-32700], + Literal[-32600], + Literal[-32601], + Literal[-32602], + Literal[-32603], + Literal[-32800], + Literal[-32000], + Literal[-32002], + int, + ] + """ + A number indicating the error type that occurred. + This must be an integer as defined in the JSON-RPC specification. + """ + message: str + """ + A string providing a short description of the error. + The message should be limited to a concise single sentence. + """ + data: Optional[Any] = None + """ + Optional primitive or structured value that contains additional information about the error. + This may include debugging information or context-specific details. + """ + + @field_validator("data", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class RunningSessionStateUpdateBase(RunningStateUpdate): + state: Literal["running"] = "running" + + +class IdleSessionStateUpdateBase(IdleStateUpdate): + state: Literal["idle"] = "idle" + + +class RequiresActionSessionStateUpdateBase(RequiresActionStateUpdate): + state: Literal["requires_action"] = "requires_action" + + +class RunningSessionStateUpdate(RunningSessionStateUpdateBase, SessionStateUpdateBase): + session_update: Annotated[Literal["state_update"], Field(alias="sessionUpdate")] = "state_update" + + +class IdleSessionStateUpdate(IdleSessionStateUpdateBase, SessionStateUpdateBase): + session_update: Annotated[Literal["state_update"], Field(alias="sessionUpdate")] = "state_update" + + +class RequiresActionSessionStateUpdate(RequiresActionSessionStateUpdateBase, SessionStateUpdateBase): + session_update: Annotated[Literal["state_update"], Field(alias="sessionUpdate")] = "state_update" + + +class SessionTerminalUpdate(TerminalUpdate): + session_update: Annotated[Literal["terminal_update"], Field(alias="sessionUpdate")] = "terminal_update" + + +class SessionTerminalOutputChunk(TerminalOutputChunk): + session_update: Annotated[Literal["terminal_output_chunk"], Field(alias="sessionUpdate")] = "terminal_output_chunk" + + +class SessionPlanRemovedUpdate(PlanRemoved): + session_update: Annotated[Literal["plan_removed"], Field(alias="sessionUpdate")] = "plan_removed" + + +class SessionInfoUpdate(SessionInfoUpdateBase): + session_update: Annotated[Literal["session_info_update"], Field(alias="sessionUpdate")] = "session_info_update" + + @field_validator("title", "updated_at", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class UsageUpdate(UsageUpdateBase): + session_update: Annotated[Literal["usage_update"], Field(alias="sessionUpdate")] = "usage_update" + + @field_validator("cost", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class PlanUpdateFile(PlanFile): + type: Literal["file"] = "file" + + +class PlanUpdateMarkdown(PlanMarkdown): + type: Literal["markdown"] = "markdown" + + +class OtherPlanUpdateContent(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + type: str + """ + Custom or future plan update content type. + + Values beginning with `_` are reserved for implementation-specific + extensions. Unknown values that do not begin with `_` are reserved for + future ACP variants. + """ + plan_id: Annotated[str, Field(alias="planId")] + """ + The plan ID to update. + """ + + +class PlanEntry(BaseModel): + content: str + """ + Human-readable description of what this task aims to accomplish. + """ + priority: Union[Literal["high"], Literal["medium"], Literal["low"], str] + """ + The relative importance of this task. + Used to indicate which tasks are most critical to the overall goal. + """ + status: Union[Literal["pending"], Literal["in_progress"], Literal["completed"], Literal["cancelled"], str] + """ + Current execution status of this task. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class PlanItems(BaseModel): + plan_id: Annotated[str, Field(alias="planId")] + """ + The plan ID to update. + """ + entries: List[PlanEntry] + """ + The list of tasks to be accomplished. + + When updating an item-based plan, the agent must send a complete list of all entries + with their current status. The client replaces that plan with each update. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("entries", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class TextAvailableCommandInput(TextCommandInput): + type: Literal["text"] = "text" + + +class AuthCapabilities(BaseModel): + terminal: Optional[TerminalAuthCapabilities] = None + """ + Whether the client supports `terminal` authentication methods. + + Optional. Omitted or `null` both mean the client does not advertise support. + The client should supply `{}` only when it can reproduce the configured + agent invocation in an interactive terminal. Supplying `{}` means the + agent may include `terminal` entries in its authentication methods. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("terminal", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class ElicitationCapabilities(BaseModel): + form: Optional[ElicitationFormCapabilities] = None + """ + Whether the client supports form-based elicitation. + + Optional. Omitted and `null` are equivalent and mean form support is not advertised. + Supplying `{}` explicitly advertises form support. + """ + url: Optional[ElicitationUrlCapabilities] = None + """ + Whether the client supports URL-based elicitation. + + Optional. Omitted or `null` both mean the client does not advertise support. + Supplying `{}` means the client supports URL-based elicitation. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + @field_validator("form", "url", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class ClientNesCapabilities(BaseModel): + jump: Optional[NesJumpCapabilities] = None + """ + Whether the client supports the `jump` suggestion kind. + """ + rename: Optional[NesRenameCapabilities] = None + """ + Whether the client supports the `rename` suggestion kind. + """ + search_and_replace: Annotated[Optional[NesSearchAndReplaceCapabilities], Field(alias="searchAndReplace")] = None + """ + Whether the client supports the `searchAndReplace` suggestion kind. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("jump", "rename", "search_and_replace", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class HttpMcpServer(McpServerHttp): + type: Literal["http"] = "http" + + +class AcpMcpServer(McpServerAcp): + type: Literal["acp"] = "acp" + + +class StdioMcpServer(McpServerStdio): + type: Literal["stdio"] = "stdio" + + +class ForkSessionRequest(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The ID of the session to fork. + """ + cwd: str + """ + The working directory for this session. Must be an absolute path. + """ + additional_directories: Annotated[Optional[List[str]], Field(alias="additionalDirectories")] = None + """ + 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. + """ + mcp_servers: Annotated[ + Optional[List[Union[HttpMcpServer, AcpMcpServer, StdioMcpServer, OtherMcpServer]]], Field(alias="mcpServers") + ] = None + """ + List of MCP servers to connect to for this session. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("additional_directories", "mcp_servers", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class ReplayFromStartVariant(ReplayFromStart): + type: Literal["start"] = "start" + + +class StartNesRequest(BaseModel): + workspace_uri: Annotated[Optional[AnyUrl], Field(alias="workspaceUri")] = None + """ + The root URI of the workspace. + """ + workspace_folders: Annotated[Optional[List[WorkspaceFolder]], Field(alias="workspaceFolders")] = None + """ + The workspace folders. + """ + repository: Optional[NesRepository] = None + """ + Repository metadata, if the workspace is a git repository. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("repository", "workspace_uri", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class NesRelatedSnippet(BaseModel): + uri: AnyUrl + """ + The URI of the file containing the snippets. + """ + excerpts: List[NesExcerpt] + """ + The code excerpts. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class NesOpenFile(BaseModel): + uri: AnyUrl + """ + The URI of the file. + """ + language_id: Annotated[str, Field(alias="languageId")] + """ + The language identifier. + """ + visible_range: Annotated[Optional[Range], Field(alias="visibleRange")] = None + """ + The visible range in the editor, if any. + """ + last_focused_ms: Annotated[Optional[int], Field(alias="lastFocusedMs", ge=0)] = None + """ + Timestamp in milliseconds since epoch of when the file was last focused. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("last_focused_ms", "visible_range", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class NesDiagnostic(BaseModel): + uri: AnyUrl + """ + The URI of the file containing the diagnostic. + """ + range: Range + """ + The range of the diagnostic. + """ + severity: Union[Literal["error"], Literal["warning"], Literal["information"], Literal["hint"], str] + """ + The severity of the diagnostic. + """ + message: str + """ + The diagnostic message. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class ClientErrorMessage(BaseModel): + id: Optional[Union[int, str]] + """ + The id of the request this response answers. + """ + error: Error + """ + Method-specific error data. + """ + + +class SelectedPermissionOutcomeVariant(SelectedPermissionOutcome): + outcome: Literal["selected"] = "selected" + + +class AcceptElicitationResponse(ElicitationAcceptAction): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + action: Literal["accept"] = "accept" + + +class TextDocumentContentChangeEvent(BaseModel): + range: Optional[Range] = None + """ + The range of the document that changed. If `None`, the entire content is replaced. + """ + text: str + """ + The new text for the range, or the full document content if `range` is `None`. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class DidFocusDocumentNotification(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The session ID for this notification. + """ + uri: AnyUrl + """ + The URI of the focused document. + """ + version: int + """ + The version number of the document. + """ + position: Position + """ + The current cursor position. + """ + visible_range: Annotated[Range, Field(alias="visibleRange")] + """ + The portion of the file currently visible in the editor viewport. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class RejectNesNotification(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The session ID for this notification. + """ + suggestion_id: Annotated[str, Field(alias="suggestionId")] + """ + The ID of the rejected suggestion. + """ + reason: Optional[Union[Literal["rejected"], Literal["ignored"], Literal["replaced"], Literal["cancelled"], str]] = ( + None + ) + """ + The reason for rejection. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("reason", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class ProtocolLevelNotification(BaseModel): + method: str + """ + The notification method name. + """ + params: Optional[CancelRequestNotification] = None + """ + Method-specific notification parameters. + """ + + +class DiffToolCallContent(Diff): + type: Literal["diff"] = "diff" + + +class TextContentBlock(TextContent): + type: Literal["text"] = "text" + + +class ImageContentBlock(ImageContent): + type: Literal["image"] = "image" + + +class AudioContentBlock(AudioContent): + type: Literal["audio"] = "audio" + + +class ResourceContentBlock(ResourceLink): + type: Literal["resource_link"] = "resource_link" + + +class EmbeddedResourceContentBlock(EmbeddedResource): + type: Literal["resource"] = "resource" + + +class Content(BaseModel): + content: Union[ + TextContentBlock, + ImageContentBlock, + AudioContentBlock, + ResourceContentBlock, + EmbeddedResourceContentBlock, + OtherContentBlock, + ] + """ + The actual content block. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class ElicitationMultiSelectPropertySchema(MultiSelectPropertySchema): + type: Literal["array"] = "array" + + +class AgentErrorMessage(BaseModel): + id: Optional[Union[int, str]] + """ + The id of the request this response answers. + """ + error: Error + """ + Method-specific error data. + """ + + +class SessionCapabilities(BaseModel): + prompt: Optional[PromptCapabilities] = None + """ + Prompt capabilities supported by the agent in `session/prompt` requests. + + Optional. Omitted or `null` both mean the agent does not advertise any + prompt extensions beyond the baseline text and resource-link content + required by `session/prompt`. + """ + mcp: Optional[McpCapabilities] = None + """ + MCP capabilities supported by the agent for session lifecycle requests. + + Optional. Omitted or `null` both mean the agent does not advertise MCP + server transport support for sessions. + """ + delete: Optional[SessionDeleteCapabilities] = None + """ + Whether the agent supports `session/delete`. + + Optional. Omitted or `null` both mean the agent does not advertise support. + Supplying `{}` means the agent supports deleting sessions from `session/list`. + """ + additional_directories: Annotated[ + Optional[SessionAdditionalDirectoriesCapabilities], Field(alias="additionalDirectories") + ] = None + """ + Whether the agent supports `additionalDirectories` on supported session lifecycle requests. + + Optional. Omitted or `null` both mean the agent does not advertise support. + Supplying `{}` means the agent supports `additionalDirectories` on + supported session lifecycle requests. + + Agents may return `SessionInfo.additionalDirectories` to report the + complete ordered additional-root list associated with a listed session. + """ + fork: Optional[SessionForkCapabilities] = None + """ + **UNSTABLE** + + This capability is not part of the spec yet, and may be removed or changed at any point. + + Whether the agent supports `session/fork`. + + Optional. Omitted or `null` both mean the agent does not advertise support. + Supplying `{}` means the agent supports forking sessions. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("additional_directories", "delete", "fork", "mcp", "prompt", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class NesDocumentEventCapabilities(BaseModel): + did_open: Annotated[Optional[NesDocumentDidOpenCapabilities], Field(alias="didOpen")] = None + """ + Whether the agent wants `document/didOpen` events. + """ + did_change: Annotated[Optional[NesDocumentDidChangeCapabilities], Field(alias="didChange")] = None + """ + Whether the agent wants `document/didChange` events, and the sync kind. + """ + did_close: Annotated[Optional[NesDocumentDidCloseCapabilities], Field(alias="didClose")] = None + """ + Whether the agent wants `document/didClose` events. + """ + did_save: Annotated[Optional[NesDocumentDidSaveCapabilities], Field(alias="didSave")] = None + """ + Whether the agent wants `document/didSave` events. + """ + did_focus: Annotated[Optional[NesDocumentDidFocusCapabilities], Field(alias="didFocus")] = None + """ + Whether the agent wants `document/didFocus` events. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("did_change", "did_close", "did_focus", "did_open", "did_save", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class ListProvidersResponse(BaseModel): + providers: List[ProviderInfo] + """ + Configurable providers with current routing info suitable for UI display. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class SessionConfigSelect(BaseModel): + current_value: Annotated[str, Field(alias="currentValue")] + """ + The currently selected value. + """ + options: Union[List[SessionConfigSelectOption], List[SessionConfigSelectGroup]] + """ + The set of selectable options. + """ + + +class NesTextEdit(BaseModel): + range: Range + """ + The range to replace. + """ + new_text: Annotated[str, Field(alias="newText")] + """ + The replacement text. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class NesEditSuggestion(BaseModel): + suggestion_id: Annotated[str, Field(alias="suggestionId")] + """ + Unique identifier for accept/reject tracking. + """ + uri: AnyUrl + """ + The URI of the file to edit. + """ + edits: Annotated[List[NesTextEdit], Field(min_length=1)] + """ + The text edits to apply. Must contain at least one edit. + """ + cursor_position: Annotated[Optional[Position], Field(alias="cursorPosition")] = None + """ + Optional suggested cursor position after applying edits. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("cursor_position", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class ContentChunk(BaseModel): + message_id: Annotated[str, Field(alias="messageId")] + """ + 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. + """ + content: Union[ + TextContentBlock, + ImageContentBlock, + AudioContentBlock, + ResourceContentBlock, + EmbeddedResourceContentBlock, + OtherContentBlock, + ] + """ + A single item of content + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. This field is chunk-scoped. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + +class UserMessage(BaseModel): + message_id: Annotated[str, Field(alias="messageId")] + """ + A unique identifier for the message. + """ + content: Optional[ + List[ + Union[ + TextContentBlock, + ImageContentBlock, + AudioContentBlock, + ResourceContentBlock, + EmbeddedResourceContentBlock, + OtherContentBlock, + ] + ] + ] = None + """ + Complete replacement content for this message. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. Omitted means no metadata update; `null` is an explicit clear signal. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + @field_validator("content", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class AgentMessage(BaseModel): + message_id: Annotated[str, Field(alias="messageId")] + """ + A unique identifier for the message. + """ + content: Optional[ + List[ + Union[ + TextContentBlock, + ImageContentBlock, + AudioContentBlock, + ResourceContentBlock, + EmbeddedResourceContentBlock, + OtherContentBlock, + ] + ] + ] = None + """ + Complete replacement content for this message. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. Omitted means no metadata update; `null` is an explicit clear signal. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + @field_validator("content", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class AgentThought(BaseModel): + message_id: Annotated[str, Field(alias="messageId")] + """ + A unique identifier for the thought message. + """ + content: Optional[ + List[ + Union[ + TextContentBlock, + ImageContentBlock, + AudioContentBlock, + ResourceContentBlock, + EmbeddedResourceContentBlock, + OtherContentBlock, + ] + ] + ] = None + """ + Complete replacement content for this thought message. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. Omitted means no metadata update; `null` is an explicit clear signal. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + @field_validator("content", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class PlanUpdateItems(PlanItems): + type: Literal["items"] = "items" + + +class PlanUpdate(BaseModel): + plan: Union[PlanUpdateItems, PlanUpdateFile, PlanUpdateMarkdown, OtherPlanUpdateContent] + """ + The updated plan content. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class AvailableCommand(BaseModel): + name: str + """ + Command name (e.g., `create_plan`, `research_codebase`). + """ + description: str + """ + Human-readable description of what the command does. + """ + input: Optional[Union[TextAvailableCommandInput, OtherAvailableCommandInput]] = None + """ + Input for the command if required + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("input", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class AvailableCommandsUpdateBase(BaseModel): + available_commands: Annotated[List[AvailableCommand], Field(alias="availableCommands")] + """ + Commands the agent can execute. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class CompactionUpdate(BaseModel): + compaction_id: Annotated[str, Field(alias="compactionId")] + """ + The Agent-owned ID of this compaction, unique within the session. + """ + status: Union[Literal["in_progress"], Literal["completed"], Literal["failed"], Literal["cancelled"], str] + """ + Current lifecycle status. + """ + summary: Optional[ + List[ + Union[ + TextContentBlock, + ImageContentBlock, + AudioContentBlock, + ResourceContentBlock, + EmbeddedResourceContentBlock, + OtherContentBlock, + ] + ] + ] = None + """ + Complete replacement user-displayable summary retained by the compaction. + """ + error: Optional[str] = None + """ + Human-readable description of why the compaction failed. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + Extensible metadata patch for this compaction. + """ + + @field_validator("error", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + @field_validator("summary", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class CompactionSummaryChunk(BaseModel): + compaction_id: Annotated[str, Field(alias="compactionId")] + """ + ID of the compaction whose summary receives this content. + """ + content: Union[ + TextContentBlock, + ImageContentBlock, + AudioContentBlock, + ResourceContentBlock, + EmbeddedResourceContentBlock, + OtherContentBlock, + ] + """ + One content block to append. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + Metadata scoped to this chunk. Omission and `null` both mean absent. + """ + + +class ClientCapabilities(BaseModel): + auth: Optional[AuthCapabilities] = None + """ + Authentication capabilities supported by the client. + Determines which authentication method types the agent may include + in its `InitializeResponse`. + + Optional. Omitted or `null` both mean the client does not advertise any + authentication-method extensions. + """ + elicitation: Optional[ElicitationCapabilities] = None + """ + Elicitation capabilities supported by the client. + Determines which elicitation modes the agent may use. + + Optional. Omitted or `null` both mean the client does not advertise + elicitation support. + """ + nes: Optional[ClientNesCapabilities] = None + """ + **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. + + Optional. Omitted or `null` both mean the client does not advertise any + NES suggestion-kind extensions. + """ + position_encodings: Annotated[ + Optional[List[Literal["utf-16", "utf-32", "utf-8"]]], Field(alias="positionEncodings") + ] = None + """ + **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. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("auth", "elicitation", "nes", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + @field_validator("position_encodings", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class NewSessionRequest(BaseModel): + cwd: str + """ + The working directory for this session. Must be an absolute path. + """ + additional_directories: Annotated[Optional[List[str]], Field(alias="additionalDirectories")] = None + """ + Additional workspace roots for this session. Each path must be absolute. + + These expand the session's workspace scope without changing `cwd`, which + remains the base for relative paths. When omitted or empty, no + additional roots are activated for the new session. + """ + mcp_servers: Annotated[ + Optional[List[Union[HttpMcpServer, AcpMcpServer, StdioMcpServer, OtherMcpServer]]], Field(alias="mcpServers") + ] = None + """ + List of MCP (Model Context Protocol) servers the agent should connect to. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("additional_directories", "mcp_servers", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class ResumeSessionRequest(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The ID of the session to resume. + """ + cwd: str + """ + The working directory for this session. Must be an absolute path. + """ + additional_directories: Annotated[Optional[List[str]], Field(alias="additionalDirectories")] = None + """ + 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. It may differ from any previously used or reported list as long as + the request `cwd` matches the session's `cwd`. + """ + mcp_servers: Annotated[ + Optional[List[Union[HttpMcpServer, AcpMcpServer, StdioMcpServer, OtherMcpServer]]], Field(alias="mcpServers") + ] = None + """ + List of MCP servers to connect to for this session. + """ + replay_from: Annotated[Optional[Union[ReplayFromStartVariant, OtherReplayFrom]], Field(alias="replayFrom")] = None + """ + Inclusive cursor describing where conversation replay should begin. + + Optional. Omitted or `null` both mean the Agent should resume without + replaying previous conversation history. Replay cursors are inclusive: + replay includes the position identified by the cursor. Supplying + `{ "type": "start" }` means the Agent should replay the whole + conversation before responding. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("replay_from", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + @field_validator("additional_directories", "mcp_servers", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class PromptRequest(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The ID of the session to send this user message to + """ + prompt: List[ + Union[ + TextContentBlock, + ImageContentBlock, + AudioContentBlock, + ResourceContentBlock, + EmbeddedResourceContentBlock, + OtherContentBlock, + ] + ] + """ + 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. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class NesSuggestContext(BaseModel): + recent_files: Annotated[Optional[List[NesRecentFile]], Field(alias="recentFiles")] = None + """ + Recently accessed files. + """ + related_snippets: Annotated[Optional[List[NesRelatedSnippet]], Field(alias="relatedSnippets")] = None + """ + Related code snippets. + """ + edit_history: Annotated[Optional[List[NesEditHistoryEntry]], Field(alias="editHistory")] = None + """ + Recent edit history. + """ + user_actions: Annotated[Optional[List[NesUserAction]], Field(alias="userActions")] = None + """ + Recent user actions (typing, navigation, etc.). + """ + open_files: Annotated[Optional[List[NesOpenFile]], Field(alias="openFiles")] = None + """ + Currently open files in the editor. + """ + diagnostics: Optional[List[NesDiagnostic]] = None + """ + Current diagnostics (errors, warnings). + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class RequestPermissionResponse(BaseModel): + outcome: Union[CancelledPermissionOutcome, SelectedPermissionOutcomeVariant, OtherPermissionOutcome] + """ + The user's decision on the permission request. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class DidChangeDocumentNotification(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The session ID for this notification. + """ + uri: AnyUrl + """ + The URI of the changed document. + """ + version: int + """ + The new version number of the document. + """ + content_changes: Annotated[List[TextDocumentContentChangeEvent], Field(alias="contentChanges")] + """ + The content changes. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("content_changes", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class ContentToolCallContent(Content): + type: Literal["content"] = "content" + + +class ElicitationSchema(BaseModel): + type: Optional[Literal["object"]] = "object" + """ + Type discriminator. Always `"object"`. + """ + title: Optional[str] = None + """ + Optional title for the schema. + + Optional. Omitted and `null` are equivalent and mean no title is provided. + """ + properties: Annotated[ + Optional[ + Dict[ + str, + Union[ + ElicitationStringPropertySchema, + ElicitationNumberPropertySchema, + ElicitationIntegerPropertySchema, + ElicitationBooleanPropertySchema, + ElicitationMultiSelectPropertySchema, + ElicitationOtherPropertySchema, + ], + ] + ], + Field(validate_default=True), + ] = {} + """ + Property definitions (must be primitive types). + """ + required: Optional[List[str]] = None + """ + List of required property names. + + Optional. Omitted and `null` are equivalent and mean no property names are required. + """ + description: Optional[str] = None + """ + Optional description of what this schema represents. + + Optional. Omitted and `null` are equivalent and mean no schema description is provided. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + @field_validator("description", "title", "type", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class ElicitationFormSessionMode(ElicitationSessionScope): + requested_schema: Annotated[ElicitationSchema, Field(alias="requestedSchema")] + """ + A JSON Schema describing the form fields to present to the user. + """ + + +class ElicitationFormRequestMode(ElicitationRequestScope): + requested_schema: Annotated[ElicitationSchema, Field(alias="requestedSchema")] + """ + A JSON Schema describing the form fields to present to the user. + """ + + +class ElicitationFormMode(RootModel[Union[ElicitationFormSessionMode, ElicitationFormRequestMode]]): + root: Union[ElicitationFormSessionMode, ElicitationFormRequestMode] + """ + Form-based elicitation mode where the client renders a form from the provided schema. + """ + + +class NesEventCapabilities(BaseModel): + document: Optional[NesDocumentEventCapabilities] = None + """ + Document event capabilities. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("document", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class SelectSessionConfigOption(SessionConfigSelect): + config_id: Annotated[str, Field(alias="configId")] + """ + Unique identifier for the configuration option. + """ + name: str + """ + Human-readable label for the option. + """ + description: Optional[str] = None + """ + Optional description for the Client to display to the user. + """ + category: Optional[ + Union[Literal["mode"], Literal["model"], Literal["model_config"], Literal["thought_level"], str] + ] = None + """ + Optional semantic category for this option (UX only). + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + type: Literal["select"] = "select" + + +class ForkSessionResponse(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + Unique identifier for the newly created forked session. + """ + config_options: Annotated[ + Optional[List[Union[SelectSessionConfigOption, BooleanSessionConfigOption, OtherSessionConfigOption]]], + Field(alias="configOptions"), + ] = None + """ + Initial session configuration options. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("config_options", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class ResumeSessionResponse(BaseModel): + config_options: Annotated[ + Optional[List[Union[SelectSessionConfigOption, BooleanSessionConfigOption, OtherSessionConfigOption]]], + Field(alias="configOptions"), + ] = None + """ + Initial session configuration options. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("config_options", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class SetSessionConfigOptionResponse(BaseModel): + config_options: Annotated[ + List[Union[SelectSessionConfigOption, BooleanSessionConfigOption, OtherSessionConfigOption]], + Field(alias="configOptions"), + ] + """ + The full set of configuration options and their current values. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("config_options", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class NesEditSuggestionVariant(NesEditSuggestion): + kind: Literal["edit"] = "edit" + + +class UserMessageChunk(ContentChunk): + session_update: Annotated[Literal["user_message_chunk"], Field(alias="sessionUpdate")] = "user_message_chunk" + + +class UserMessageUpdate(UserMessage): + session_update: Annotated[Literal["user_message"], Field(alias="sessionUpdate")] = "user_message" + + +class AgentMessageChunk(ContentChunk): + session_update: Annotated[Literal["agent_message_chunk"], Field(alias="sessionUpdate")] = "agent_message_chunk" + + +class AgentMessageUpdate(AgentMessage): + session_update: Annotated[Literal["agent_message"], Field(alias="sessionUpdate")] = "agent_message" + + +class AgentThoughtChunk(ContentChunk): + session_update: Annotated[Literal["agent_thought_chunk"], Field(alias="sessionUpdate")] = "agent_thought_chunk" + + +class AgentThoughtUpdate(AgentThought): + session_update: Annotated[Literal["agent_thought"], Field(alias="sessionUpdate")] = "agent_thought" + + +class SessionPlanUpdate(PlanUpdate): + session_update: Annotated[Literal["plan_update"], Field(alias="sessionUpdate")] = "plan_update" + + +class AvailableCommandsUpdate(AvailableCommandsUpdateBase): + session_update: Annotated[Literal["available_commands_update"], Field(alias="sessionUpdate")] = ( + "available_commands_update" + ) + + @field_validator("available_commands", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class SessionCompactionUpdate(CompactionUpdate): + session_update: Annotated[Literal["compaction_update"], Field(alias="sessionUpdate")] = "compaction_update" + + +class SessionCompactionSummaryChunk(CompactionSummaryChunk): + session_update: Annotated[Literal["compaction_summary_chunk"], Field(alias="sessionUpdate")] = ( + "compaction_summary_chunk" + ) + + +class ToolCallContentChunk(BaseModel): + tool_call_id: Annotated[str, Field(alias="toolCallId")] + """ + The ID of the tool call this content belongs to. + """ + content: Union[ContentToolCallContent, DiffToolCallContent, TerminalToolCallContent, OtherToolCallContent] + """ + A single item of content produced by the tool call. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. This field is chunk-scoped. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + +class ConfigOptionUpdateBase(BaseModel): + config_options: Annotated[ + List[Union[SelectSessionConfigOption, BooleanSessionConfigOption, OtherSessionConfigOption]], + Field(alias="configOptions"), + ] + """ + The full set of configuration options and their current values. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class InitializeRequest(BaseModel): + protocol_version: Annotated[int, Field(alias="protocolVersion", ge=0, le=65535)] + """ + The latest protocol version supported by the client. + """ + info: Implementation + """ + Information about the implementation sending this initialize request. + """ + capabilities: Annotated[Optional[ClientCapabilities], Field(validate_default=True)] = {} + """ + Capabilities supported by the client. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("protocol_version", mode="before") + @classmethod + def coerce_protocol_version_validator(cls, v: Any, info: ValidationInfo) -> Any: + return coerce_protocol_version(v, info) + + @field_validator("capabilities", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class SuggestNesRequest(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The session ID for this request. + """ + uri: AnyUrl + """ + The URI of the document to suggest for. + """ + version: int + """ + The version number of the document. + """ + position: Position + """ + The current cursor position. + """ + selection: Optional[Range] = None + """ + The current text selection range, if any. + """ + trigger_kind: Annotated[ + Union[Literal["automatic"], Literal["diagnostic"], Literal["manual"], str], Field(alias="triggerKind") + ] + """ + What triggered this suggestion request. + """ + context: Optional[NesSuggestContext] = None + """ + Context for the suggestion, included based on agent capabilities. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class ClientResponseMessage(BaseModel): + id: Optional[Union[int, str]] + """ + The id of the request this response answers. + """ + result: Union[ + RequestPermissionResponse, + ConnectMcpResponse, + DisconnectMcpResponse, + Union[ + AcceptElicitationResponse, DeclineElicitationResponse, CancelElicitationResponse, OtherElicitationResponse + ], + Any, + ] + """ + Method-specific response data. + """ + + +class ClientResponse(RootModel[Union[ClientResponseMessage, ClientErrorMessage]]): + root: Union[ClientResponseMessage, ClientErrorMessage] + """ + A JSON-RPC response object. + """ + + +class ClientNotification(BaseModel): + method: str + """ + The notification method name. + """ + params: Optional[ + Union[ + CancelSessionNotification, + DidOpenDocumentNotification, + DidChangeDocumentNotification, + DidCloseDocumentNotification, + DidSaveDocumentNotification, + DidFocusDocumentNotification, + AcceptNesNotification, + RejectNesNotification, + MessageMcpNotification, + Any, + ] + ] = None + """ + Method-specific notification parameters. + """ + + +class ToolCallUpdate(BaseModel): + tool_call_id: Annotated[str, Field(alias="toolCallId")] + """ + Unique identifier for this tool call within the session. + """ + name: Optional[str] = None + """ + **UNSTABLE** + + This capability is not part of the spec yet, and may be removed or changed at any point. + + Programmatic name of the tool being invoked. + + This field is optional and has patch semantics. Omission means no + change, `null` clears the name, and a string replaces it. For a tool + call ID the client has not seen before, omission or `null` means that no + tool name is available. + """ + title: Optional[str] = None + """ + Human-readable title describing what the tool is doing. + """ + kind: Optional[ + Union[ + Literal["read"], + Literal["edit"], + Literal["delete"], + Literal["move"], + Literal["search"], + Literal["execute"], + Literal["think"], + Literal["fetch"], + Literal["switch_mode"], + Literal["other"], + str, + ] + ] = None + """ + The category of tool being invoked. + Helps clients choose appropriate icons and UI treatment. + """ + status: Optional[ + Union[ + Literal["pending"], + Literal["in_progress"], + Literal["completed"], + Literal["failed"], + Literal["cancelled"], + str, + ] + ] = None + """ + Current execution status of the tool call. + """ + content: Optional[ + List[Union[ContentToolCallContent, DiffToolCallContent, TerminalToolCallContent, OtherToolCallContent]] + ] = None + """ + Content produced by the tool call. + """ + locations: Optional[List[ToolCallLocation]] = None + """ + File locations affected by this tool call. + Enables "follow-along" features in clients. + """ + raw_input: Annotated[Optional[Any], Field(alias="rawInput")] = None + """ + Raw input parameters sent to the tool. + """ + raw_output: Annotated[Optional[Any], Field(alias="rawOutput")] = None + """ + Raw output returned by the tool. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + The _meta property is reserved by ACP to allow clients and agents to attach additional + metadata to their interactions. Omitted means no metadata update; `null` is an + explicit clear signal. Implementations MUST NOT make assumptions about values at these keys. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + + @field_validator("kind", "name", "raw_input", "raw_output", "status", "title", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + @field_validator("content", "locations", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class ToolCallPermissionSubject(BaseModel): + tool_call: Annotated[ToolCallUpdate, Field(alias="toolCall")] + """ + Details about the tool call requiring permission. + """ + + +class CreateFormSessionElicitationRequestBase(ElicitationSessionScope): + requested_schema: Annotated[ElicitationSchema, Field(alias="requestedSchema")] + """ + A JSON Schema describing the form fields to present to the user. + """ + + +class CreateFormRequestElicitationRequestBase(ElicitationRequestScope): + requested_schema: Annotated[ElicitationSchema, Field(alias="requestedSchema")] + """ + A JSON Schema describing the form fields to present to the user. + """ + + +class CreateFormSessionElicitationRequest(CreateFormSessionElicitationRequestBase, CreateFormElicitationRequestBase): + message: str + """ + A human-readable message describing what input is needed. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + mode: Literal["form"] = "form" + + +class CreateFormRequestElicitationRequest(CreateFormRequestElicitationRequestBase, CreateFormElicitationRequestBase): + message: str + """ + A human-readable message describing what input is needed. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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. + + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + """ + mode: Literal["form"] = "form" + + +class NesCapabilities(BaseModel): + events: Optional[NesEventCapabilities] = None + """ + Events the agent wants to receive. + """ + context: Optional[NesContextCapabilities] = None + """ + Context the agent wants attached to each suggestion request. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("context", "events", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class NewSessionResponse(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + Unique identifier for the created session. + + Used in all subsequent requests for this conversation. + """ + config_options: Annotated[ + Optional[List[Union[SelectSessionConfigOption, BooleanSessionConfigOption, OtherSessionConfigOption]]], + Field(alias="configOptions"), + ] = None + """ + Initial session configuration options. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("config_options", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class SuggestNesResponse(BaseModel): + suggestions: List[ + Union[ + NesEditSuggestionVariant, + NesJumpSuggestionVariant, + NesRenameSuggestionVariant, + NesSearchAndReplaceSuggestionVariant, + OtherNesSuggestion, + ] + ] + """ + The list of suggestions. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class ToolCallContentChunkUpdate(ToolCallContentChunk): + session_update: Annotated[Literal["tool_call_content_chunk"], Field(alias="sessionUpdate")] = ( + "tool_call_content_chunk" + ) + + +class SessionToolCallUpdate(ToolCallUpdate): + session_update: Annotated[Literal["tool_call_update"], Field(alias="sessionUpdate")] = "tool_call_update" + + +class ConfigOptionUpdate(ConfigOptionUpdateBase): + session_update: Annotated[Literal["config_option_update"], Field(alias="sessionUpdate")] = "config_option_update" + + @field_validator("config_options", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class ClientRequest(BaseModel): + id: Optional[Union[int, str]] + """ + The request id used to correlate the matching response. + """ + method: str + """ + The method name to invoke. + """ + params: Optional[ + Union[ + InitializeRequest, + LoginAuthRequest, + ListProvidersRequest, + SetProviderRequest, + DisableProviderRequest, + LogoutAuthRequest, + NewSessionRequest, + ListSessionsRequest, + DeleteSessionRequest, + ForkSessionRequest, + ResumeSessionRequest, + CloseSessionRequest, + PromptRequest, + StartNesRequest, + SuggestNesRequest, + CloseNesRequest, + MessageMcpRequest, + Union[ + SetSessionConfigOptionIdRequest, + SetSessionConfigOptionBooleanRequest, + SetSessionConfigOptionOtherRequest, + ], + Any, + ] + ] = None + """ + Method-specific request parameters. + """ + + +class ToolCallPermissionSubjectVariant(ToolCallPermissionSubject): + type: Literal["tool_call"] = "tool_call" + + +class AgentCapabilities(BaseModel): + session: Optional[SessionCapabilities] = None + """ + Session capabilities supported by the agent. + + Optional. Omitted or `null` both mean the agent does not support the + `session/*` method surface. Supplying `{}` means the agent supports the + baseline session methods: `session/new`, `session/prompt`, + `session/cancel`, and `session/update`. + """ + auth: Optional[AgentAuthCapabilities] = None + """ + Authentication-related extension capabilities supported by the agent. + + Optional. Omitted or `null` both mean the agent does not advertise any + authentication-related extensions. This field does not advertise support + for `auth/login` or `auth/logout`; those methods are advertised by a + non-empty `authMethods` list in the `initialize` response. + """ + providers: Optional[ProvidersCapabilities] = None + """ + **UNSTABLE** + + This capability is not part of the spec yet, and may be removed or changed at any point. + + Provider configuration capabilities supported by the agent. + + Optional. Omitted or `null` both mean the agent does not advertise support. + Supplying `{}` means the agent supports provider configuration methods. + """ + nes: Optional[NesCapabilities] = None + """ + **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. + + Optional. Omitted or `null` both mean the agent does not advertise support + for NES methods. + """ + position_encoding: Annotated[Optional[Literal["utf-16", "utf-32", "utf-8"]], Field(alias="positionEncoding")] = None + """ + **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. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("auth", "nes", "position_encoding", "providers", "session", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class UpdateSessionNotification(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The ID of the session this update pertains to. + """ + update: Union[ + UserMessageChunk, + UserMessageUpdate, + AgentMessageChunk, + AgentMessageUpdate, + AgentThoughtChunk, + AgentThoughtUpdate, + ToolCallContentChunkUpdate, + SessionToolCallUpdate, + SessionTerminalUpdate, + SessionTerminalOutputChunk, + SessionPlanUpdate, + SessionPlanRemovedUpdate, + AvailableCommandsUpdate, + ConfigOptionUpdate, + SessionInfoUpdate, + UsageUpdate, + SessionCompactionUpdate, + SessionCompactionSummaryChunk, + OtherSessionUpdate, + Union[ + RunningSessionStateUpdate, IdleSessionStateUpdate, RequiresActionSessionStateUpdate, OtherSessionStateUpdate + ], + ] + """ + The actual update content. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + +class RequestPermissionRequest(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The session ID for this request. + """ + title: str + """ + Human-readable title for the permission prompt. + + This title is specific to the permission prompt and does not update any + subject's displayed title. + """ + description: Optional[str] = None + """ + Optional human-readable explanation of why permission is needed. + + This text is specific to the permission prompt and does not update any + subject's displayed content. Omitted or `null` both mean no separate + permission description was provided. + """ + subject: Optional[ + Union[ToolCallPermissionSubjectVariant, CommandPermissionSubjectVariant, OtherPermissionSubject] + ] = None + """ + Optional structured context about the operation requiring permission. + + Omitted or `null` both mean no structured subject was provided. + """ + options: Annotated[List[PermissionOption], Field(min_length=1)] + """ + Available permission options for the user to choose from. + Must contain at least one option. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("description", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + +class InitializeResponse(BaseModel): + protocol_version: Annotated[int, Field(alias="protocolVersion", ge=0, le=65535)] + """ + The protocol version the client specified if supported by the agent, + or the latest protocol version supported by the agent. + + The client should disconnect, if it doesn't support this version. + """ + info: Implementation + """ + Information about the implementation sending this initialize response. + """ + capabilities: Annotated[Optional[AgentCapabilities], Field(validate_default=True)] = {} + """ + Capabilities supported by the agent. + """ + auth_methods: Annotated[ + Optional[List[Union[TerminalAuthMethod, AgentAuthMethod, OtherAuthMethod]]], Field(alias="authMethods") + ] = None + """ + Authentication methods supported by the agent. + + Optional. Omitted or empty means the agent does not advertise the + authentication method surface. Supplying one or more valid methods means + the agent MUST support both `auth/login` and `auth/logout`. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_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/v2/draft/extensibility) + """ + + @field_validator("capabilities", mode="wrap") + @classmethod + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) + + @field_validator("auth_methods", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + +class AgentNotification(BaseModel): + method: str + """ + The notification method name. + """ + params: Optional[Union[UpdateSessionNotification, CompleteElicitationNotification, MessageMcpNotification, Any]] = ( + None + ) + """ + Method-specific notification parameters. + """ + + +class AgentRequest(BaseModel): + id: Optional[Union[int, str]] + """ + The request id used to correlate the matching response. + """ + method: str + """ + The method name to invoke. + """ + params: Optional[ + Union[ + RequestPermissionRequest, + ConnectMcpRequest, + MessageMcpRequest, + DisconnectMcpRequest, + Union[ + Union[CreateOtherSessionElicitationRequest, CreateOtherRequestElicitationRequest], + Union[CreateFormSessionElicitationRequest, CreateFormRequestElicitationRequest], + Union[CreateUrlSessionElicitationRequest, CreateUrlRequestElicitationRequest], + ], + Any, + ] + ] = None + """ + Method-specific request parameters. + """ + + +class AgentResponseMessage(BaseModel): + id: Optional[Union[int, str]] + """ + The id of the request this response answers. + """ + result: Union[ + InitializeResponse, + LoginAuthResponse, + ListProvidersResponse, + SetProviderResponse, + DisableProviderResponse, + LogoutAuthResponse, + NewSessionResponse, + ListSessionsResponse, + DeleteSessionResponse, + ForkSessionResponse, + ResumeSessionResponse, + CloseSessionResponse, + SetSessionConfigOptionResponse, + PromptResponse, + StartNesResponse, + SuggestNesResponse, + CloseNesResponse, + Any, + ] + """ + Method-specific response data. + """ + + +class AgentResponse(RootModel[Union[AgentResponseMessage, AgentErrorMessage]]): + root: Union[AgentResponseMessage, AgentErrorMessage] + """ + A JSON-RPC response object. + """ From 3ef92ae2c4af4fb50a03c1f48aba1eaac8939cac Mon Sep 17 00:00:00 2001 From: PsiACE Date: Mon, 31 Aug 2026 05:04:12 +0800 Subject: [PATCH 3/5] test(schema): cover experimental v2 bindings --- tests/test_gen_all.py | 22 ++++++++++++++++--- tests/test_v2_schema.py | 48 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+), 3 deletions(-) create mode 100644 tests/test_v2_schema.py diff --git a/tests/test_gen_all.py b/tests/test_gen_all.py index e1d586e..dec76f3 100644 --- a/tests/test_gen_all.py +++ b/tests/test_gen_all.py @@ -2,6 +2,7 @@ from acp.schema import ReadTextFileRequest from scripts.gen_all import resolve_ref, schema_source_paths +from scripts.gen_meta import generate_meta from scripts.gen_schema import generate_schema @@ -13,6 +14,7 @@ def test_generated_field_descriptions_are_introspectable() -> None: def test_resolve_ref_accepts_schema_release_tags() -> None: assert resolve_ref("schema-v1.16.0") == "refs/tags/schema-v1.16.0" + assert resolve_ref("schema-v2.0.0-alpha.3") == "refs/tags/schema-v2.0.0-alpha.3" def test_resolve_ref_keeps_legacy_version_tags() -> None: @@ -27,6 +29,12 @@ def test_schema_release_tags_prefer_v1_schema_layout() -> None: ) +def test_v2_generation_uses_v2_schema_layout() -> None: + assert schema_source_paths("refs/tags/schema-v2.0.0-alpha.3", 2) == ( + ("schema/v2/schema.unstable.json", "schema/v2/meta.unstable.json"), + ) + + def test_legacy_tags_keep_legacy_schema_layout_first() -> None: assert schema_source_paths("refs/tags/v0.13.6")[0] == ( "schema/schema.unstable.json", @@ -49,8 +57,16 @@ def test_parse_args_can_skip_format(monkeypatch) -> None: def test_codegen_check_is_clean_and_read_only() -> None: - output = Path("src/acp/schema.py") - before = output.read_bytes() + outputs = ( + Path("src/acp/meta.py"), + Path("src/acp/schema.py"), + Path("src/acp/experimental/v2/meta.py"), + Path("src/acp/experimental/v2/schema.py"), + ) + before = {output: output.read_bytes() for output in outputs} assert generate_schema(check=True) - assert output.read_bytes() == before + assert generate_meta(check=True) + assert generate_schema(check=True, protocol_version=2) + assert generate_meta(check=True, protocol_version=2) + assert {output: output.read_bytes() for output in outputs} == before diff --git a/tests/test_v2_schema.py b/tests/test_v2_schema.py new file mode 100644 index 0000000..e775bbb --- /dev/null +++ b/tests/test_v2_schema.py @@ -0,0 +1,48 @@ +import pytest +from pydantic import ValidationError + +from acp.experimental.v2 import PROTOCOL_VERSION +from acp.experimental.v2.schema import ( + AgentMessageChunk, + OtherSessionUpdate, + TextContentBlock, + UpdateSessionNotification, +) + + +def test_v2_models_fill_protocol_discriminators() -> None: + update = AgentMessageChunk( + message_id="message-1", + content=TextContentBlock(text="hello"), + ) + + assert PROTOCOL_VERSION == 2 + assert update.model_dump(by_alias=True, exclude_none=True) == { + "sessionUpdate": "agent_message_chunk", + "messageId": "message-1", + "content": {"type": "text", "text": "hello"}, + } + + +def test_v2_open_union_preserves_unknown_updates() -> None: + notification = UpdateSessionNotification.model_validate({ + "sessionId": "session-1", + "update": {"sessionUpdate": "_vendor_status", "status": "waiting"}, + }) + + assert isinstance(notification.update, OtherSessionUpdate) + assert notification.model_dump(by_alias=True, exclude_none=True)["update"] == { + "sessionUpdate": "_vendor_status", + "status": "waiting", + } + + +def test_v2_open_union_rejects_malformed_known_updates() -> None: + with pytest.raises(ValidationError): + UpdateSessionNotification.model_validate({ + "sessionId": "session-1", + "update": { + "sessionUpdate": "agent_message_chunk", + "content": {"type": "text", "text": "hello"}, + }, + }) From fe9479a8743cb4189dcd6f3a9ee241614c668ba4 Mon Sep 17 00:00:00 2001 From: PsiACE Date: Mon, 31 Aug 2026 05:25:10 +0800 Subject: [PATCH 4/5] fix(codegen): expose protocol method metadata --- scripts/gen_meta.py | 2 ++ src/acp/experimental/v2/__init__.py | 4 ++-- src/acp/experimental/v2/meta.py | 1 + src/acp/meta.py | 1 + tests/test_v2_schema.py | 3 ++- 5 files changed, 8 insertions(+), 3 deletions(-) diff --git a/scripts/gen_meta.py b/scripts/gen_meta.py index f423269..e871856 100644 --- a/scripts/gen_meta.py +++ b/scripts/gen_meta.py @@ -54,6 +54,7 @@ def render_meta(*, protocol_version: int = 1) -> str: data = json.loads(meta_json.read_text("utf-8")) agent_methods = data.get("agentMethods", {}) client_methods = data.get("clientMethods", {}) + protocol_methods = data.get("protocolMethods") version = data.get("version", 1) header_lines = [f"# Generated from {meta_json.relative_to(ROOT)}. Do not edit by hand."] if version_file.exists(): @@ -66,6 +67,7 @@ def render_meta(*, protocol_version: int = 1) -> str: + "\n" + f"AGENT_METHODS = {json.dumps(agent_methods, indent=4)}\n" + f"CLIENT_METHODS = {json.dumps(client_methods, indent=4)}\n" + + (f"PROTOCOL_METHODS = {json.dumps(protocol_methods, indent=4)}\n" if protocol_methods is not None else "") + f"PROTOCOL_VERSION = {int(version)}\n" ) result = subprocess.run( # noqa: S603 diff --git a/src/acp/experimental/v2/__init__.py b/src/acp/experimental/v2/__init__.py index b50388a..c5ee37e 100644 --- a/src/acp/experimental/v2/__init__.py +++ b/src/acp/experimental/v2/__init__.py @@ -1,5 +1,5 @@ """Experimental ACP protocol v2 bindings.""" -from .meta import AGENT_METHODS, CLIENT_METHODS, PROTOCOL_VERSION +from .meta import AGENT_METHODS, CLIENT_METHODS, PROTOCOL_METHODS, PROTOCOL_VERSION -__all__ = ["AGENT_METHODS", "CLIENT_METHODS", "PROTOCOL_VERSION"] +__all__ = ["AGENT_METHODS", "CLIENT_METHODS", "PROTOCOL_METHODS", "PROTOCOL_VERSION"] diff --git a/src/acp/experimental/v2/meta.py b/src/acp/experimental/v2/meta.py index ad96d06..2fdaf60 100644 --- a/src/acp/experimental/v2/meta.py +++ b/src/acp/experimental/v2/meta.py @@ -37,4 +37,5 @@ "elicitation_create": "elicitation/create", "elicitation_complete": "elicitation/complete", } +PROTOCOL_METHODS = {"cancel_request": "$/cancel_request"} PROTOCOL_VERSION = 2 diff --git a/src/acp/meta.py b/src/acp/meta.py index 37adae4..d852669 100644 --- a/src/acp/meta.py +++ b/src/acp/meta.py @@ -46,4 +46,5 @@ "elicitation_create": "elicitation/create", "elicitation_complete": "elicitation/complete", } +PROTOCOL_METHODS = {"cancel_request": "$/cancel_request"} PROTOCOL_VERSION = 1 diff --git a/tests/test_v2_schema.py b/tests/test_v2_schema.py index e775bbb..a63709c 100644 --- a/tests/test_v2_schema.py +++ b/tests/test_v2_schema.py @@ -1,7 +1,7 @@ import pytest from pydantic import ValidationError -from acp.experimental.v2 import PROTOCOL_VERSION +from acp.experimental.v2 import PROTOCOL_METHODS, PROTOCOL_VERSION from acp.experimental.v2.schema import ( AgentMessageChunk, OtherSessionUpdate, @@ -17,6 +17,7 @@ def test_v2_models_fill_protocol_discriminators() -> None: ) assert PROTOCOL_VERSION == 2 + assert PROTOCOL_METHODS == {"cancel_request": "$/cancel_request"} assert update.model_dump(by_alias=True, exclude_none=True) == { "sessionUpdate": "agent_message_chunk", "messageId": "message-1", From 7408b7e5b9793a944ee4a96dc078975a35795f93 Mon Sep 17 00:00:00 2001 From: PsiACE Date: Wed, 2 Sep 2026 14:01:50 +0800 Subject: [PATCH 5/5] fix(codegen): isolate v2 schema semantics --- scripts/_schema_semantics.py | 1 + scripts/gen_schema.py | 2 +- scripts/gen_schema_v1.py | 1 + scripts/gen_schema_v2.py | 1 + src/acp/_schema_base.py | 41 ----------------- src/acp/experimental/v2/_schema_base.py | 59 +++++++++++++++++++++++++ src/acp/experimental/v2/schema.py | 2 +- 7 files changed, 64 insertions(+), 43 deletions(-) create mode 100644 src/acp/experimental/v2/_schema_base.py diff --git a/scripts/_schema_semantics.py b/scripts/_schema_semantics.py index 4784267..33ade90 100644 --- a/scripts/_schema_semantics.py +++ b/scripts/_schema_semantics.py @@ -20,6 +20,7 @@ class SchemaSemantics: schema_json: Path version_file: Path schema_out: Path + base_class: str model_name_map: dict[str, str] compatibility_aliases: str = "" diff --git a/scripts/gen_schema.py b/scripts/gen_schema.py index 8c6de65..e790395 100644 --- a/scripts/gen_schema.py +++ b/scripts/gen_schema.py @@ -97,7 +97,7 @@ def render_schema(semantics: SchemaSemantics) -> str: collapse_root_models=True, skip_root_model=True, output_model_type=DataModelType.PydanticV2BaseModel, - base_class="acp._schema_base.BaseModel", + base_class=semantics.base_class, use_specialized_enum=False, use_standard_collections=False, use_union_operator=False, diff --git a/scripts/gen_schema_v1.py b/scripts/gen_schema_v1.py index ba4bab2..d1c382b 100644 --- a/scripts/gen_schema_v1.py +++ b/scripts/gen_schema_v1.py @@ -227,6 +227,7 @@ class Jsonrpc(Enum): schema_json=ROOT / "schema" / "schema.json", version_file=ROOT / "schema" / "VERSION", schema_out=ROOT / "src" / "acp" / "schema.py", + base_class="acp._schema_base.BaseModel", model_name_map=MODEL_NAME_MAP, compatibility_aliases=COMPATIBILITY_ALIASES, ) diff --git a/scripts/gen_schema_v2.py b/scripts/gen_schema_v2.py index 00fb4f4..7ed52ba 100644 --- a/scripts/gen_schema_v2.py +++ b/scripts/gen_schema_v2.py @@ -227,5 +227,6 @@ schema_json=ROOT / "schema" / "v2" / "schema.json", version_file=ROOT / "schema" / "v2" / "VERSION", schema_out=ROOT / "src" / "acp" / "experimental" / "v2" / "schema.py", + base_class="acp.experimental.v2._schema_base.BaseModel", model_name_map=MODEL_NAME_MAP, ) diff --git a/src/acp/_schema_base.py b/src/acp/_schema_base.py index 282c529..ad979b3 100644 --- a/src/acp/_schema_base.py +++ b/src/acp/_schema_base.py @@ -19,48 +19,7 @@ class BaseModel(pydantic.BaseModel): """Runtime behavior shared by generated ACP schema models.""" - # datamodel-code-generator does not emit the `not` constraints used by ACP's - # open unions, so catch-all variants must reject tags owned by known variants. _reserved_tags: ClassVar[dict[str, tuple[str, frozenset[str]]]] = { - "OtherAuthMethod": ("type", frozenset({"agent", "terminal"})), - "OtherAvailableCommandInput": ("type", frozenset({"text"})), - "OtherContentBlock": ("type", frozenset({"audio", "image", "resource", "resource_link", "text"})), - "OtherDiffChange": ("operation", frozenset({"add", "copy", "delete", "modify", "move"})), - "OtherMcpServer": ("type", frozenset({"acp", "http", "stdio"})), - "OtherNesSuggestion": ("kind", frozenset({"edit", "jump", "rename", "searchAndReplace"})), - "OtherPermissionOutcome": ("outcome", frozenset({"cancelled", "selected"})), - "OtherPermissionSubject": ("type", frozenset({"command", "tool_call"})), - "OtherPlanUpdateContent": ("type", frozenset({"file", "items", "markdown"})), - "OtherReplayFrom": ("type", frozenset({"start"})), - "OtherSessionConfigOption": ("type", frozenset({"boolean", "select"})), - "OtherSessionStateUpdate": ("state", frozenset({"idle", "requires_action", "running"})), - "OtherSessionUpdate": ( - "sessionUpdate", - frozenset({ - "agent_message", - "agent_message_chunk", - "agent_thought", - "agent_thought_chunk", - "available_commands_update", - "compaction_summary_chunk", - "compaction_update", - "config_option_update", - "plan_removed", - "plan_update", - "session_info_update", - "state_update", - "terminal_output_chunk", - "terminal_update", - "tool_call_content_chunk", - "tool_call_update", - "usage_update", - "user_message", - "user_message_chunk", - }), - ), - "OtherState": ("state", frozenset({"idle", "requires_action", "running"})), - "OtherToolCallContent": ("type", frozenset({"content", "diff", "terminal"})), - "SetSessionConfigOptionOtherRequest": ("type", frozenset({"boolean", "id"})), "CreateOtherSessionElicitationRequest": ("mode", frozenset({"form", "url"})), "CreateOtherRequestElicitationRequest": ("mode", frozenset({"form", "url"})), "OtherElicitationResponse": ("action", frozenset({"accept", "cancel", "decline"})), diff --git a/src/acp/experimental/v2/_schema_base.py b/src/acp/experimental/v2/_schema_base.py new file mode 100644 index 0000000..0dd0fe2 --- /dev/null +++ b/src/acp/experimental/v2/_schema_base.py @@ -0,0 +1,59 @@ +from typing import ClassVar + +from acp._schema_base import BaseModel as _BaseModel + + +class BaseModel(_BaseModel): + """Runtime behavior shared by generated ACP v2 schema models.""" + + # datamodel-code-generator does not emit the `not` constraints used by ACP's + # open unions, so catch-all variants must reject tags owned by known variants. + _reserved_tags: ClassVar[dict[str, tuple[str, frozenset[str]]]] = { + "OtherAuthMethod": ("type", frozenset({"agent", "terminal"})), + "OtherAvailableCommandInput": ("type", frozenset({"text"})), + "OtherContentBlock": ("type", frozenset({"audio", "image", "resource", "resource_link", "text"})), + "OtherDiffChange": ("operation", frozenset({"add", "copy", "delete", "modify", "move"})), + "OtherMcpServer": ("type", frozenset({"acp", "http", "stdio"})), + "OtherNesSuggestion": ("kind", frozenset({"edit", "jump", "rename", "searchAndReplace"})), + "OtherPermissionOutcome": ("outcome", frozenset({"cancelled", "selected"})), + "OtherPermissionSubject": ("type", frozenset({"command", "tool_call"})), + "OtherPlanUpdateContent": ("type", frozenset({"file", "items", "markdown"})), + "OtherReplayFrom": ("type", frozenset({"start"})), + "OtherSessionConfigOption": ("type", frozenset({"boolean", "select"})), + "OtherSessionStateUpdate": ("state", frozenset({"idle", "requires_action", "running"})), + "OtherSessionUpdate": ( + "sessionUpdate", + frozenset({ + "agent_message", + "agent_message_chunk", + "agent_thought", + "agent_thought_chunk", + "available_commands_update", + "compaction_summary_chunk", + "compaction_update", + "config_option_update", + "plan_removed", + "plan_update", + "session_info_update", + "state_update", + "terminal_output_chunk", + "terminal_update", + "tool_call_content_chunk", + "tool_call_update", + "usage_update", + "user_message", + "user_message_chunk", + }), + ), + "OtherState": ("state", frozenset({"idle", "requires_action", "running"})), + "OtherToolCallContent": ("type", frozenset({"content", "diff", "terminal"})), + "SetSessionConfigOptionOtherRequest": ("type", frozenset({"boolean", "id"})), + "CreateOtherSessionElicitationRequest": ("mode", frozenset({"form", "url"})), + "CreateOtherRequestElicitationRequest": ("mode", frozenset({"form", "url"})), + "OtherElicitationResponse": ("action", frozenset({"accept", "cancel", "decline"})), + "ElicitationOtherPropertySchema": ( + "type", + frozenset({"array", "boolean", "integer", "number", "string"}), + ), + "OtherMultiSelectItems": ("type", frozenset({"string"})), + } diff --git a/src/acp/experimental/v2/schema.py b/src/acp/experimental/v2/schema.py index 6c3b5e5..065a560 100644 --- a/src/acp/experimental/v2/schema.py +++ b/src/acp/experimental/v2/schema.py @@ -7,7 +7,7 @@ from typing import Annotated, Any, Dict, List, Literal, Optional, Union from acp._deserialize import coerce_protocol_version, skip_invalid_items, use_default_on_error -from acp._schema_base import BaseModel +from acp.experimental.v2._schema_base import BaseModel from pydantic import ( AnyUrl, AwareDatetime,