From 26ef9a97446bd754f63b9291ec7963b520b94908 Mon Sep 17 00:00:00 2001 From: alex Date: Tue, 10 Nov 2026 11:54:22 +0100 Subject: [PATCH 1/2] feat(mcp)!: adopt stateless MCP-over-ACP binding --- docs/experimental-v2.md | 12 +- docs/quickstart.md | 77 +- examples/mcp_over_acp.py | 99 +++ schema/VERSION | 2 +- schema/meta.json | 2 - schema/schema.json | 989 +++++++++++++++------ schema/v2/VERSION | 2 +- schema/v2/meta.json | 2 - schema/v2/schema.json | 1083 ++++++++++++++--------- scripts/gen_schema_v1.py | 13 +- scripts/gen_schema_v2.py | 23 +- src/acp/__init__.py | 16 +- src/acp/_mcp.py | 18 + src/acp/_schema_base.py | 20 + src/acp/agent/connection.py | 57 +- src/acp/client/connection.py | 17 +- src/acp/experimental/v2/_methods.py | 3 + src/acp/experimental/v2/_router.py | 2 + src/acp/experimental/v2/_schema_base.py | 7 +- src/acp/experimental/v2/agent.py | 40 +- src/acp/experimental/v2/client.py | 15 +- src/acp/experimental/v2/interfaces.py | 38 +- src/acp/experimental/v2/meta.py | 4 +- src/acp/experimental/v2/schema.py | 542 ++++++++---- src/acp/interfaces.py | 44 +- src/acp/meta.py | 4 +- src/acp/schema.py | 461 ++++++++-- tests/conftest.py | 15 +- tests/test_protocol_method_coverage.py | 43 +- tests/test_stateless_mcp.py | 247 ++++++ tests/test_v2_routing.py | 10 +- tests/test_v2_runtime.py | 10 +- 32 files changed, 2760 insertions(+), 1157 deletions(-) create mode 100644 examples/mcp_over_acp.py create mode 100644 src/acp/_mcp.py create mode 100644 tests/test_stateless_mcp.py diff --git a/docs/experimental-v2.md b/docs/experimental-v2.md index e62ecb6d..087dbe17 100644 --- a/docs/experimental-v2.md +++ b/docs/experimental-v2.md @@ -3,7 +3,7 @@ > **Experimental.** Protocol v2 is a draft. Import it from `acp.experimental` and > expect its API and generated models to change with the upstream schema. -The bindings use `schema-v2.0.0-alpha.5`. +The bindings use `schema-v2.0.0-alpha.7`. The v2 runtime is separate from the stable v1 API. Like v1, connection methods and agent/client handlers accept expanded, snake-case parameters. Responses and @@ -155,3 +155,13 @@ by the shared connection layer, as in v1: cancelling the task awaiting a request sends a best-effort cancellation to the peer, and an incoming cancellation cancels the handler task, which answers with its result or `-32800`. `session/cancel` remains available for cancelling active session work. + +## Stateless MCP-over-ACP + +V2 uses the same [stateless MCP binding](quickstart.md#stateless-mcp-over-acp) +as v1. Use the independent `v2.schema.McpResultResponse`, `McpErrorResponse`, +`McpError`, and `MessageMcpResponse` types. The agent advertises support with +`capabilities.session.mcp.acp = {}`; omission or null does not advertise support. +After ACP initialization, agents send `mcp_message` requests and providers send +`notify_mcp` notifications with explicit `server_id` and `request_id` strings. +The old MCP connect/disconnect methods and reverse requests are removed. diff --git a/docs/quickstart.md b/docs/quickstart.md index 14c43d9a..00d619ca 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -159,7 +159,7 @@ update = AgentMessageChunk( ## Session notices (unstable) -The v1 bindings use `schema-v1.23.0`. Clients that can display live advisory +The v1 bindings use `schema-v1.24.1`. Clients that can display live advisory notices advertise `ClientCapabilities(session=ClientSessionCapabilities(notices=NoticeCapabilities()))` in `initialize`; these models are available from `acp.schema`. @@ -189,7 +189,7 @@ nested objects are not valid form values. ## Additional v1 protocol methods -The SDK exposes all agent and client methods in the bundled `schema-v1.23.0` +The SDK exposes all agent and client methods in the bundled `schema-v1.24.1` method tables. `session/delete` and `logout` are stable and do not require `use_unstable_protocol=True`. The other methods in the table below are unstable; enable that flag on the receiving connection (or `run_agent`) to route them. @@ -200,9 +200,8 @@ Check the peer's advertised capabilities before calling these methods. | `session/delete` | `delete_session(session_id=...)` | Agent | | `providers/list`, `providers/set`, `providers/disable` | `list_providers`, `set_provider`, `disable_provider` | Agent | | `logout` | `logout()` | Agent | -| `mcp/connect`, `mcp/disconnect` | `connect_mcp`, `disconnect_mcp` | Client | -| `mcp/message` (request) | `mcp_message` | Either peer | -| `mcp/message` (notification) | `notify_mcp` | Either peer | +| `mcp/message` (request) | `mcp_message` | Client/provider | +| `mcp/message` (notification) | `notify_mcp` | Agent | | `nes/start`, `nes/suggest`, `nes/close` | `start_nes`, `suggest_nes`, `close_nes` | Agent | | `nes/accept`, `nes/reject` | `accept_nes`, `reject_nes` | Agent | | `document/didOpen`, `document/didChange`, `document/didClose`, `document/didSave`, `document/didFocus` | `did_open`, `did_change`, `did_close`, `did_save`, `did_focus` | Agent | @@ -223,10 +222,70 @@ session. The SDK dispatches these calls to your implementation; it does not provide session storage or provider management itself. Missing request handlers return the JSON-RPC method-not-found error. -MCP requests return the inner JSON result unchanged, including `null`. Use -`notify_mcp` for one-way MCP messages. Both APIs accept `connection_id`, `method`, -and optional `params`. These methods share the same connections and routers -across stdio, HTTP, and WebSocket transports. +## Stateless MCP-over-ACP + +The unstable native binding targets **MCP 2026-07-28**. A provider advertises an +`AcpMcpServer(name=..., server_id=...)` in session setup after checking the +agent's `mcpCapabilities.acp` capability. Register the provider's handler before +publishing the declaration: the agent may call it before session setup returns. +There is no MCP initialization or connect/disconnect exchange. + +An agent calls its connection's `mcp_message`; the client/provider implements +that handler. Supply a fresh string `request_id` for every operation, including +an interactive-tool retry. This logical MCP ID is separate from the outer ACP +JSON-RPC request ID. Include the required MCP metadata in the inner parameters: + +```python +from uuid import uuid4 +from acp import McpErrorResponse + +response = await connection.mcp_message( + server_id="project-tools", + request_id=uuid4().hex, + method="tools/list", + params={ + "_meta": { + "io.modelcontextprotocol/protocolVersion": "2026-07-28", + "io.modelcontextprotocol/clientCapabilities": {}, + }, + }, + trace="outer ACP metadata", +) +if isinstance(response, McpErrorResponse): + handle_mcp_error(response.error) +else: + use_mcp_result(response.result) +``` + +Providers return `McpResultResponse(result=...)` or +`McpErrorResponse(error=McpError(code=..., message=...))`. Results are opaque JSON, +including explicit `null`, tool errors with `isError`, and interactive +`input_required` results. Error data preserves omission versus explicit null, +and unknown inner error fields survive. Outer ACP failures raise `RequestError`; +an inner MCP error, even code `-32000`, remains inside the response carrier. +Send exactly one outcome; receivers prefer `result` if both keys are received. + +The provider sends `notify_mcp(server_id=..., request_id=..., method=..., params=...)` +for an active request; the agent implements `notify_mcp` to receive it. Keep the +same server and logical request IDs and stop notifications before sending the +final outcome. Consumers must correlate notifications with active operations +and ignore unknown or completed ones. There are no provider-originated MCP requests. + +The SDK provides typed envelopes and routing. Applications own server registrations, +MCP metadata/version validation, duplicate-active-ID rejection, operation admission, +and notification lifetimes. They also decide how to handle interactive input; +retry with fresh IDs and preserve opaque request state. Cancelling the task awaiting +`mcp_message` uses the existing ACP cancellation mechanism described below. +These methods work over stdio, HTTP, and WebSocket ACP connections. + +**Migration:** `connect_mcp`, `disconnect_mcp`, and `connection_id` are removed. +Replace them with server-addressed requests carrying `server_id` and `request_id`, +add per-request MCP metadata, and wrap handler outcomes in the typed carrier. +Older MCP revisions and the connection-oriented prototype are not supported. + +Run `uv run python examples/mcp_over_acp.py` for a local request/progress example. +See the [upstream binding specification](https://agentclientprotocol.com/rfds/mcp-over-acp) +for registration, subscription, and error-code requirements. ## Request cancellation diff --git a/examples/mcp_over_acp.py b/examples/mcp_over_acp.py new file mode 100644 index 00000000..b09f6ace --- /dev/null +++ b/examples/mcp_over_acp.py @@ -0,0 +1,99 @@ +"""Run a native MCP request and progress notification over an in-memory ACP connection. + +Run with: uv run python examples/mcp_over_acp.py +No MCP initialization, HTTP listener, or external provider is needed. +""" + +import asyncio +import logging +from typing import Any +from uuid import uuid4 + +from acp import Client, McpError, McpErrorResponse, McpResultResponse, MessageMcpResponse, RequestError +from acp._transport import memory_transport_pair +from acp.agent.connection import AgentSideConnection +from acp.client.connection import ClientSideConnection + + +class EchoProvider: + connection: ClientSideConnection + + def on_connect(self, connection: ClientSideConnection) -> None: + self.connection = connection + + async def mcp_message( + self, server_id: str, request_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any + ) -> MessageMcpResponse: + if server_id != "echo": + raise RequestError(-33001, "Server registration unavailable") + params = params or {} + meta = params.get("_meta") + if not isinstance(meta, dict) or not isinstance(meta.get("io.modelcontextprotocol/protocolVersion"), str): + return McpErrorResponse(error=McpError(code=-32602, message="Missing MCP protocol version")) + if meta["io.modelcontextprotocol/protocolVersion"] != "2026-07-28": + return McpErrorResponse( + error=McpError( + code=-32022, + message="Unsupported MCP protocol version", + data={"supported": ["2026-07-28"], "requested": meta["io.modelcontextprotocol/protocolVersion"]}, + ) + ) + if not isinstance(meta.get("io.modelcontextprotocol/clientCapabilities"), dict): + return McpErrorResponse(error=McpError(code=-32602, message="Missing MCP client capabilities")) + if method != "tools/call" or params.get("name") != "echo": + return McpErrorResponse(error=McpError(code=-32601, message="Unknown MCP operation")) + await self.connection.notify_mcp( + server_id=server_id, + request_id=request_id, + method="notifications/progress", + params={"progressToken": meta["progressToken"], "progress": 1, "total": 1}, + ) + return McpResultResponse( + result={ + "resultType": "complete", + "content": [{"type": "text", "text": params["arguments"]["message"]}], + "isError": False, + } + ) + + +class Consumer: + async def notify_mcp( + self, server_id: str, request_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any + ) -> None: + logging.info("%s / %s: %s %s", server_id, request_id, method, params) + + +async def main() -> None: + agent_transport, client_transport = memory_transport_pair() + async with ( + AgentSideConnection(Consumer(), agent_transport, use_unstable_protocol=True) as agent, + ClientSideConnection(EchoProvider(), client_transport, use_unstable_protocol=True), + ): + # The provider has already registered "echo" locally. In an application, + # advertise AcpMcpServer(name="echo", server_id="echo") in session setup + # after checking the agent's MCP-over-ACP capability. + connection: Client = agent + response = await connection.mcp_message( + server_id="echo", + request_id=uuid4().hex, + method="tools/call", + params={ + "name": "echo", + "arguments": {"message": "Hello over ACP"}, + "_meta": { + "io.modelcontextprotocol/protocolVersion": "2026-07-28", + "io.modelcontextprotocol/clientCapabilities": {}, + "progressToken": "echo-progress", + }, + }, + ) + if isinstance(response, McpErrorResponse): + logging.info("MCP error: %s", response.error) + else: + logging.info("MCP result: %s", response.result) + + +if __name__ == "__main__": + logging.basicConfig(level=logging.INFO) + asyncio.run(main()) diff --git a/schema/VERSION b/schema/VERSION index cb282c42..ee41110d 100644 --- a/schema/VERSION +++ b/schema/VERSION @@ -1 +1 @@ -refs/tags/schema-v1.23.0 +refs/tags/schema-v1.24.1 diff --git a/schema/meta.json b/schema/meta.json index d8937f38..956449fc 100644 --- a/schema/meta.json +++ b/schema/meta.json @@ -40,9 +40,7 @@ "terminal_release": "terminal/release", "terminal_wait_for_exit": "terminal/wait_for_exit", "terminal_kill": "terminal/kill", - "mcp_connect": "mcp/connect", "mcp_message": "mcp/message", - "mcp_disconnect": "mcp/disconnect", "elicitation_create": "elicitation/create", "elicitation_complete": "elicitation/complete" }, diff --git a/schema/schema.json b/schema/schema.json index 041f6edc..4938b2ff 100644 --- a/schema/schema.json +++ b/schema/schema.json @@ -235,15 +235,6 @@ } ] }, - { - "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.", @@ -253,15 +244,6 @@ } ] }, - { - "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/extensibility)", @@ -2595,47 +2577,23 @@ "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`.", + "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": { "serverId": { - "description": "The ACP MCP server ID that was provided by the component declaring the MCP server.", + "description": "The declared ACP MCP server receiving this request.", "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/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.", + "requestId": { + "description": "The caller-generated identifier for the inner MCP request.", "allOf": [ { - "$ref": "#/$defs/McpConnectionId" + "$ref": "#/$defs/McpRequestId" } ] }, @@ -2662,43 +2620,20 @@ } }, "required": [ - "connectionId", + "serverId", + "requestId", "method" ], - "x-side": "both", + "x-side": "client", "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.", + "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/message` to route requests to the component that declared the server.", "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/extensibility)", - "type": [ - "object", - "null" - ], - "x-deserialize-default-on-error": true, - "additionalProperties": true - } - }, - "required": [ - "connectionId" - ], - "x-side": "client", - "x-method": "mcp/disconnect" + "McpRequestId": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nIdentifies an inner MCP request active against a server on this ACP connection.\n\nGenerated by the caller and preserved unchanged by proxies. This is distinct\nfrom the outer ACP JSON-RPC request ID.", + "type": "string" }, "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/extensibility)" @@ -2901,15 +2836,6 @@ "$ref": "#/$defs/ExtResponse" } ] - }, - { - "title": "MessageMcpResponse", - "description": "Successful result returned by an MCP-over-ACP `mcp/message` request.", - "allOf": [ - { - "$ref": "#/$defs/MessageMcpResponse" - } - ] } ] } @@ -5577,11 +5503,6 @@ "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/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", @@ -5707,15 +5628,6 @@ } ] }, - { - "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/extensibility)", @@ -6065,6 +5977,60 @@ "$ref": "#/$defs/CompactionSummaryChunk" } ] + }, + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAnnounces a child session created and owned by this session, or updates\nthat ownership association's metadata.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "subagent_update" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/SubagentUpdate" + } + ] + }, + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA message upsert observed in this session's transcript, sent to or\nreceived from another session.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "session_message" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/SessionMessage" + } + ] + }, + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nOne content block appended to a sent or received session message.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "session_message_chunk" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/SessionMessageChunk" + } + ] } ], "discriminator": { @@ -6965,20 +6931,24 @@ "content" ] }, - "CompleteElicitationNotification": { - "description": "Notification sent by the agent when a URL-based elicitation is complete.", + "SubagentSessionCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nClient-initiated session mutations permitted for a specific subagent session.\n\nA mutation requires an explicit per-child capability; support for the method\non ordinary sessions does not grant support on a child.", "type": "object", "properties": { - "elicitationId": { - "description": "The ID of the elicitation that completed.", - "allOf": [ + "cancel": { + "description": "Permits the client to cancel this child's current work without ending\nthe session. Omitted or `null` means unsupported; an object (including\n`{}`) means supported.", + "anyOf": [ { - "$ref": "#/$defs/ElicitationId" + "$ref": "#/$defs/SessionCancelCapabilities" + }, + { + "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/extensibility)", + "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.", "type": [ "object", "null" @@ -6986,38 +6956,12 @@ "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`.", + "SessionCancelCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapability to cancel work in a subagent session without ending that session.\n\nSupplying `{}` advertises support; an omitted or `null` `cancel` does not.", "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/extensibility)", "type": [ @@ -7027,76 +6971,513 @@ "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/extensibility)" + } }, - "ClientRequest": { - "description": "A JSON-RPC request object.", - "type": "object", - "properties": { - "id": { - "description": "The request id used to correlate the matching response.", + "StateUpdate": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCurrent foreground-work state of a reusable child session.\n\nEach update is a whole-object snapshot. Idle does not terminate the child;\nthe parent can message it again, transitioning it back to running.\nBackground activity may still emit other session updates while idle.", + "anyOf": [ + { + "description": "Foreground work is in progress.", + "type": "object", + "properties": { + "state": { + "type": "string", + "const": "running" + } + }, + "required": [ + "state" + ], "allOf": [ { - "$ref": "#/$defs/RequestId" + "$ref": "#/$defs/RunningStateUpdate" } ] }, - "method": { - "description": "The method name to invoke.", - "type": "string" + { + "description": "The child is ready to process another prompt.", + "type": "object", + "properties": { + "state": { + "type": "string", + "const": "idle" + } + }, + "required": [ + "state" + ], + "allOf": [ + { + "$ref": "#/$defs/IdleStateUpdate" + } + ] }, - "params": { - "description": "Method-specific request parameters.", - "anyOf": [ + { + "description": "Foreground work is blocked on user action.", + "type": "object", + "properties": { + "state": { + "type": "string", + "const": "requires_action" + } + }, + "required": [ + "state" + ], + "allOf": [ { - "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/initialization)", - "allOf": [ - { - "$ref": "#/$defs/InitializeRequest" - } - ] - }, - { - "title": "AuthenticateRequest", - "description": "Authenticates the client using the specified authentication method.\n\nCalled when the agent requires authentication before allowing session creation.\nThe client provides an authentication method ID that was advertised during\ninitialization and whose type defines the `authenticate` flow.\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/initialization)", - "allOf": [ - { - "$ref": "#/$defs/AuthenticateRequest" - } - ] - }, - { - "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" - } - ] - }, - { + "$ref": "#/$defs/RequiresActionStateUpdate" + } + ] + }, + { + "description": "The Agent cannot currently determine foreground activity.\n\nThis replaces previously confirmed activity without ending the work or session.", + "type": "object", + "properties": { + "state": { + "type": "string", + "const": "unknown" + } + }, + "required": [ + "state" + ], + "allOf": [ + { + "$ref": "#/$defs/UnknownStateUpdate" + } + ] + }, + { + "title": "other", + "description": "Custom or future state.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Other unknown values are reserved for future ACP variants.", + "type": "object", + "properties": { + "state": { + "description": "Unrecognized state discriminator.", + "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" + ] + }, + { + "type": "object", + "properties": { + "state": { + "type": "string", + "const": "unknown" + } + }, + "required": [ + "state" + ] + } + ] + }, + "additionalProperties": true + } + ] + }, + "RunningStateUpdate": { + "description": "Foreground work is in progress.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP for additional metadata.\nImplementations MUST NOT make assumptions about values at these keys.\nOptional; omitted and `null` mean no metadata for this state snapshot.", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "IdleStateUpdate": { + "description": "The child is ready to process another prompt.", + "type": "object", + "properties": { + "stopReason": { + "description": "Reason foreground work stopped. Optional; omitted or `null` means not reported.", + "anyOf": [ + { + "$ref": "#/$defs/StopReason" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "usage": { + "description": "**UNSTABLE** Token usage for completed foreground work.\n\nOptional; omitted or `null` means not reported.", + "anyOf": [ + { + "$ref": "#/$defs/Usage" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "The _meta property is reserved by ACP for additional metadata.\nImplementations MUST NOT make assumptions about values at these keys.\nOptional; omitted and `null` mean no metadata for this state snapshot.", + "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 for additional metadata.\nImplementations MUST NOT make assumptions about values at these keys.\nOptional; omitted and `null` mean no metadata for this state snapshot.", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "UnknownStateUpdate": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe Agent cannot currently determine foreground activity.\n\nReport this when activity becomes unobservable, not merely because the child\nhas been quiet. The Client MUST stop presenting the previous state as confirmed\ncurrent activity, but may retain it as last known. A later state replaces this\nsnapshot normally.\n\nThis is not a task outcome or session closure. It does not cancel work, resolve\npending requests, or revoke capabilities; capabilities are updated separately.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP for additional metadata.\nImplementations MUST NOT make assumptions about values at these keys.\nOptional; omitted and `null` mean no metadata for this state snapshot.", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "SubagentUpdate": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nNotification that the enclosing parent session created and owns a child session.\n\nLater updates modify the existing association's metadata, not its ownership.\n\nSent on the immediate parent session. The first update for an unknown\n[`SubagentUpdate::session_id`] announces the child and MUST be sent\nbefore any live child traffic or live message naming the child as sender\nor recipient. Parents may message and reuse an announced child across\nmultiple operations.\nChild events are delivered automatically on the same connection; no child\nload, resume, or subscription is needed.\n\nOnly the subagent session ID is required. Omitted patch fields keep their\nprevious values; `null` clears them. Clearing capabilities disables child\nmutations. Clearing state leaves current activity unset/unconfirmed: it does\nnot imply idle, stop work, or create an `unknown` state snapshot. A concrete\nstate replaces the entire previous state object, not the session.\nThe title and description provide the parent's display metadata for the\nchild. They do not replace the content of individual messages or operations.", + "type": "object", + "properties": { + "sessionId": { + "description": "The opaque session ID identifying the child in all ACP messages.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "title": { + "description": "The parent's human-readable display title for this child. It need not be unique.\n\nOmitted means unchanged; `null` clears it. If unset, the Client chooses\na fallback presentation.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "description": { + "description": "The parent's human-readable description of the child's role or purpose.\n\nOmitted means unchanged; `null` clears it. If unset, the Client chooses\na fallback presentation. This is current display metadata, not the\nhistory of instructions sent to the child.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "capabilities": { + "description": "Client-initiated session mutations permitted for this subagent session.\n\nOmitted means unchanged; `null` clears the capability set and disables\nchild mutations. If never supplied, no session mutations are permitted.\nRead-only operations retain their normal protocol semantics and capability\nrequirements. A concrete object replaces the whole capability set.", + "anyOf": [ + { + "$ref": "#/$defs/SubagentSessionCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "state": { + "description": "Current state snapshot for the child session.\n\nOmitted means unchanged; `null` clears the current activity without\nasserting idle or sending an `unknown` snapshot. A concrete state\nreplaces the previous state object wholesale. If never supplied, the\ncurrent activity is unset/unconfirmed.", + "anyOf": [ + { + "$ref": "#/$defs/StateUpdate" + }, + { + "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/extensibility)\nOmitted means unchanged; `null` removes the metadata.", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId" + ] + }, + "SessionMessage": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAn upsert for an inter-session message.", + "type": "object", + "properties": { + "messageId": { + "description": "Identifier of this message within the enclosing session's transcript.", + "allOf": [ + { + "$ref": "#/$defs/MessageId" + } + ] + }, + "senderSessionId": { + "description": "Optional sending session identity; omission or `null` retains a known value.", + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "recipientSessionId": { + "description": "Optional receiving session identity; omission or `null` retains a known value.", + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "content": { + "description": "Omitted leaves content unchanged; `null` or `[]` clears it.\nA non-empty array replaces all content.", + "type": [ + "array", + "null" + ], + "items": { + "$ref": "#/$defs/ContentBlock" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "_meta": { + "description": "Omitted leaves metadata unchanged; `null` removes it.\n\nImplementations MUST NOT make assumptions about values in `_meta`.", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "messageId" + ] + }, + "SessionMessageChunk": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA streamed content block of an inter-session message.", + "type": "object", + "properties": { + "messageId": { + "description": "Identifier of this message within the enclosing session's transcript.", + "allOf": [ + { + "$ref": "#/$defs/MessageId" + } + ] + }, + "senderSessionId": { + "description": "Optional sending session identity; omission or `null` retains a known value.", + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "recipientSessionId": { + "description": "Optional receiving session identity; omission or `null` retains a known value.", + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "content": { + "description": "A single content block appended to the message.", + "allOf": [ + { + "$ref": "#/$defs/ContentBlock" + } + ] + }, + "_meta": { + "description": "Optional and nullable chunk-scoped metadata; omitted or `null` means none.\n\nImplementations MUST NOT make assumptions about values in `_meta`.", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "messageId", + "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/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "elicitationId" + ], + "x-side": "client", + "x-method": "elicitation/complete" + }, + "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/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/initialization)", + "allOf": [ + { + "$ref": "#/$defs/InitializeRequest" + } + ] + }, + { + "title": "AuthenticateRequest", + "description": "Authenticates the client using the specified authentication method.\n\nCalled when the agent requires authentication before allowing session creation.\nThe client provides an authentication method ID that was advertised during\ninitialization and whose type defines the `authenticate` flow.\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/initialization)", + "allOf": [ + { + "$ref": "#/$defs/AuthenticateRequest" + } + ] + }, + { + "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": [ @@ -7231,15 +7612,6 @@ } ] }, - { - "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/extensibility)", @@ -7357,6 +7729,18 @@ ], "x-deserialize-default-on-error": true }, + "subagents": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhether the client understands exposed subagent sessions.\n\nOptional and nullable. Omitted or `null` both mean the client does not\nadvertise support.\nSupplying `{}` means the client understands child associations, work-state\nsnapshots, session-directed messages, and restricted-session semantics.", + "anyOf": [ + { + "$ref": "#/$defs/SubagentCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, "plan": { "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhether the client supports `plan_update` and `plan_removed` session updates.\n\nOptional. Omitted or `null` both mean the client does not advertise support.\nSupplying `{}` means the client can receive both update types.", "anyOf": [ @@ -7553,6 +7937,21 @@ "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nClient support for presenting live advisory notices to the user.", "type": "object" }, + "SubagentCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapability marker for exposing reusable child sessions as restricted ACP sessions.\n\nSupplying `{}` advertises support for child association and state updates,\nsession-directed messages, and restricted-session semantics. The client\nmust advertise this capability before the agent sends subagent updates or\nsession-directed messages.", + "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.", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, "PlanCapabilities": { "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapabilities for receiving `plan_update` and `plan_removed` session updates.", "type": "object", @@ -8102,7 +8501,7 @@ ] }, "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`.", + "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/message`.", "type": "object", "properties": { "name": { @@ -9259,24 +9658,6 @@ } ] }, - { - "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.", @@ -9807,50 +10188,84 @@ } } }, - "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" + "MessageMcpResponse": { + "description": "**UNSTABLE**\n\nThe successful outer ACP `mcp/message` response carries exactly one\ninner MCP outcome: an opaque result (including JSON null), or an MCP error.\nOuter ACP errors are reserved for binding and runtime failures.\n\nBoth branches require their carrier key. An error must be a non-null object.\nUnknown outer fields are ignored; inner result and error fields are preserved.\nCarrier `_meta` is optional; null or invalid values are treated as absent.\nSenders must include exactly one outcome; receivers prefer `result` if both are present.", + "anyOf": [ + { + "title": "Result", + "description": "An opaque inner MCP result.", + "type": "object", + "properties": { + "result": { + "description": "Required, even if JSON null." + }, + "_meta": { + "description": "Optional ACP carrier metadata.", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true } + }, + "required": [ + "result" ] }, - "_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/extensibility)", - "type": [ - "object", - "null" - ], - "x-deserialize-default-on-error": true, - "additionalProperties": true + { + "title": "Error", + "description": "A structured inner MCP error.", + "type": "object", + "properties": { + "error": { + "description": "Required, non-null MCP error object.", + "allOf": [ + { + "$ref": "#/$defs/McpError" + } + ] + }, + "_meta": { + "description": "Optional ACP carrier metadata.", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "error" + ] } - }, - "required": [ - "connectionId" ], "x-side": "client", - "x-method": "mcp/connect" + "x-method": "mcp/message" }, - "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`.", + "McpError": { + "description": "**UNSTABLE**\n\nAn inner MCP error, distinct from an outer ACP binding or runtime error.\n\n`code` and `message` are required and non-null. `data` is optional;\nexplicit `null` is preserved separately from an omitted key.", "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/extensibility)", - "type": [ - "object", - "null" - ], - "x-deserialize-default-on-error": true, - "additionalProperties": true + "code": { + "description": "Inner MCP error code; never an ACP error code.", + "type": "integer", + "format": "int32" + }, + "message": { + "description": "Inner MCP error message.", + "type": "string" + }, + "data": { + "description": "Optional error data; explicit null is retained." } }, - "x-side": "client", - "x-method": "mcp/disconnect" + "required": [ + "code", + "message" + ], + "additionalProperties": true }, "ClientNotification": { "description": "A JSON-RPC notification object.", @@ -10362,6 +10777,56 @@ } ] }, + "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\nSent by the provider to the consumer for an active request (including\nsubscription acknowledgements and updates); the outer envelope has no `id`.", + "type": "object", + "properties": { + "serverId": { + "description": "The declared ACP MCP server handling the associated request.", + "allOf": [ + { + "$ref": "#/$defs/McpServerAcpId" + } + ] + }, + "requestId": { + "description": "The identifier of the active inner MCP request.", + "allOf": [ + { + "$ref": "#/$defs/McpRequestId" + } + ] + }, + "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/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "serverId", + "requestId", + "method" + ], + "x-side": "agent", + "x-method": "mcp/message" + }, "CancelRequestNotification": { "description": "Notification to cancel an ongoing request.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation)", "type": "object", diff --git a/schema/v2/VERSION b/schema/v2/VERSION index feb38860..c7bdc61f 100644 --- a/schema/v2/VERSION +++ b/schema/v2/VERSION @@ -1 +1 @@ -refs/tags/schema-v2.0.0-alpha.5 +refs/tags/schema-v2.0.0-alpha.7 diff --git a/schema/v2/meta.json b/schema/v2/meta.json index 47d7973c..1912c791 100644 --- a/schema/v2/meta.json +++ b/schema/v2/meta.json @@ -31,9 +31,7 @@ "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" }, diff --git a/schema/v2/schema.json b/schema/v2/schema.json index 759b9d47..0c867dc5 100644 --- a/schema/v2/schema.json +++ b/schema/v2/schema.json @@ -329,15 +329,6 @@ "$ref": "#/$defs/ExtResponse" } ] - }, - { - "title": "MessageMcpResponse", - "description": "Successful result returned by an MCP-over-ACP `mcp/message` request.", - "allOf": [ - { - "$ref": "#/$defs/MessageMcpResponse" - } - ] } ] } @@ -479,24 +470,6 @@ } ] }, - { - "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.", @@ -641,15 +614,6 @@ } ] }, - { - "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.", @@ -659,15 +623,6 @@ } ] }, - { - "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)", @@ -3448,47 +3403,23 @@ "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`.", + "MessageMcpRequest": { + "description": "**UNSTABLE**\n\nRequest parameters for `mcp/message`, sent from consumer to provider.", "type": "object", "properties": { "serverId": { - "description": "The ACP MCP server ID that was provided by the component declaring the MCP server.", + "description": "The declared ACP MCP server receiving this request.", "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.", + "requestId": { + "description": "The caller-generated identifier for the inner MCP request.", "allOf": [ { - "$ref": "#/$defs/McpConnectionId" + "$ref": "#/$defs/McpRequestId" } ] }, @@ -3497,7 +3428,7 @@ "type": "string" }, "params": { - "description": "Optional inner MCP params.\n\nIf omitted or set to `null`, the inner MCP message has no params.", + "description": "Optional inner MCP params; null is equivalent to omission.", "type": [ "object", "null" @@ -3505,7 +3436,7 @@ "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)", + "description": "ACP extension metadata (not inner MCP params._meta); null is equivalent to omission.", "type": [ "object", "null" @@ -3515,43 +3446,20 @@ } }, "required": [ - "connectionId", + "serverId", + "requestId", "method" ], - "x-side": "both", + "x-side": "client", "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.", + "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/message` to route requests to the component that declared the server.", "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" + "McpRequestId": { + "description": "**UNSTABLE**\n\nIdentifies an inner MCP request active against a server on this ACP connection.\nGenerated by the caller and preserved unchanged by proxies, independently of\nthe outer ACP JSON-RPC request ID.", + "type": "string" }, "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)" @@ -3736,15 +3644,6 @@ "$ref": "#/$defs/ExtResponse" } ] - }, - { - "title": "MessageMcpResponse", - "description": "Successful result returned by an MCP-over-ACP `mcp/message` request.", - "allOf": [ - { - "$ref": "#/$defs/MessageMcpResponse" - } - ] } ] } @@ -5249,6 +5148,15 @@ "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, + "availableCommands": { + "description": "Initial commands the agent can execute in this session.\n\nOptional. Omitted or empty means no initial commands are advertised.\nSenders MUST use an array, not `null`; receivers treat `null` like omission.\nLater `available_commands_update` notifications replace this list.", + "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": [ @@ -5579,6 +5487,121 @@ "currentValue" ] }, + "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" + ] + }, "ListSessionsResponse": { "description": "Response from listing sessions.", "type": "object", @@ -5723,6 +5746,15 @@ "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, + "availableCommands": { + "description": "Initial commands the agent can execute in this session.\n\nOptional. Omitted or empty means no initial commands are advertised.\nSenders MUST use an array, not `null`; receivers treat `null` like omission.\nLater `available_commands_update` notifications replace this list.", + "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": [ @@ -5752,6 +5784,15 @@ "x-deserialize-default-on-error": true, "x-deserialize-skip-invalid-items": true }, + "availableCommands": { + "description": "Initial commands the agent can execute in this session.\n\nOptional. Omitted or empty means no initial commands are advertised.\nSenders MUST use an array, not `null`; receivers treat `null` like omission.\nLater `available_commands_update` notifications replace this list.", + "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": [ @@ -6361,11 +6402,6 @@ "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", @@ -6491,15 +6527,6 @@ } ] }, - { - "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)", @@ -6923,30 +6950,84 @@ ] }, { - "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.", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAnnounces a child session created and owned by this session, or updates\nthat ownership association's metadata.", "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" + "type": "string", + "const": "subagent_update" } }, "required": [ "sessionUpdate" ], - "not": { - "anyOf": [ - { - "type": "object", - "properties": { - "sessionUpdate": { - "type": "string", - "const": "user_message_chunk" - } - }, - "required": [ - "sessionUpdate" + "allOf": [ + { + "$ref": "#/$defs/SubagentUpdate" + } + ] + }, + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA message upsert observed in this session's transcript, sent to or\nreceived from another session.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "session_message" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/SessionMessage" + } + ] + }, + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nOne content block appended to a sent or received session message.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "session_message_chunk" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/SessionMessageChunk" + } + ] + }, + { + "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" ] }, { @@ -7176,6 +7257,42 @@ "required": [ "sessionUpdate" ] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "subagent_update" + } + }, + "required": [ + "sessionUpdate" + ] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "session_message" + } + }, + "required": [ + "sessionUpdate" + ] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "session_message_chunk" + } + }, + "required": [ + "sessionUpdate" + ] } ] }, @@ -7504,6 +7621,21 @@ } } }, + "UnknownStateUpdate": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe Agent cannot currently determine foreground activity.\n\nReport this when activity becomes unobservable, not merely because the session\nhas been quiet. The Client MUST stop presenting the previous state as confirmed\ncurrent activity, but may retain it as last known. A later state replaces this\nsnapshot normally.\n\nThis is not a task outcome or session closure. It does not cancel work, resolve\npending requests, or revoke capabilities; capabilities are updated separately.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP for additional metadata.\nImplementations MUST NOT make assumptions about values at these keys.\nOptional; omitted and `null` mean no metadata for this state snapshot.", + "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": [ @@ -7561,6 +7693,24 @@ } ] }, + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe Agent cannot currently determine foreground activity.\nThis replaces previously confirmed activity without ending the work or session.", + "type": "object", + "properties": { + "state": { + "type": "string", + "const": "unknown" + } + }, + "required": [ + "state" + ], + "allOf": [ + { + "$ref": "#/$defs/UnknownStateUpdate" + } + ] + }, { "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.", @@ -7611,6 +7761,18 @@ "required": [ "state" ] + }, + { + "type": "object", + "properties": { + "state": { + "type": "string", + "const": "unknown" + } + }, + "required": [ + "state" + ] } ] }, @@ -8184,121 +8346,6 @@ "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", @@ -8556,28 +8603,242 @@ } ] }, - "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`.", + "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" + ] + }, + "SubagentSessionCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nClient-initiated session mutations permitted for a specific subagent session.\n\nA mutation requires an explicit per-child capability; support for the method\non ordinary sessions does not grant support on a child.", + "type": "object", + "properties": { + "cancel": { + "description": "Permits the client to cancel this child's current work without ending\nthe session. Omitted or `null` means unsupported; an object (including\n`{}`) means supported.", + "anyOf": [ + { + "$ref": "#/$defs/SessionCancelCapabilities" + }, + { + "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.", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "SessionCancelCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapability to cancel work in a subagent session without ending that session.\n\nSupplying `{}` advertises support; an omitted or `null` `cancel` does not.", + "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 + } + } + }, + "SubagentUpdate": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nNotification that the enclosing parent session created and owns a child session.\n\nLater updates modify the existing association's metadata, not its ownership.\n\nSent on the immediate parent session. The first update for an unknown\n[`SubagentUpdate::session_id`] announces the child and MUST be sent\nbefore any live request or notification bearing the child's session ID,\nincluding messages naming it as sender or recipient. Child events are\ndelivered automatically; no separate child load, resume, or subscription is needed.\nUnderstanding this update, registering child sessions, and applying their\noperation restrictions are baseline v2 requirements; no Client capability\nis required.\n\nOnly [`SubagentUpdate::session_id`] is required. Other fields have\npatch semantics: omitted fields leave the stored value unchanged, `null`\nclears or unsets the value, and concrete values replace it. For `state`,\n`null` removes the current state report and leaves activity unconfirmed;\nit does not report idle or cancellation. A child whose capabilities are\nunset permits no Client-initiated session mutations.\n\nThe title and description provide the parent's display metadata for the\nchild. Agents SHOULD mirror known child state changes in the parent's\n[`SubagentUpdate::state`] using the same [`StateUpdate`] snapshot as the\nordinary `state_update` notification on the child session. This reports\nchild state, not a separate parent-owned lifecycle. Consumers should\ntreat duplicate reports idempotently.\nCompleting or cancelling work does not end the association: the parent may\nmessage the same child again. Individual messages and their outcomes do not\nchange this association.", + "type": "object", + "properties": { + "sessionId": { + "description": "The opaque session ID identifying the child in all ACP messages.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "title": { + "description": "The parent's human-readable display title for this child. It need not be unique.\n\nOptional and nullable. Omitted means unchanged; `null` clears it. If no\ntitle is set, the Client chooses a fallback presentation.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "description": { + "description": "The parent's human-readable description of the child's role or purpose.\n\nOptional and nullable. Omitted means unchanged; `null` clears it. This is\ncurrent display metadata, not the history of instructions sent to the child.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "capabilities": { + "description": "Client-initiated session mutations permitted for this subagent session.\n\nRead-only operations retain their normal protocol semantics and\ncapability requirements.", + "anyOf": [ + { + "$ref": "#/$defs/SubagentSessionCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "state": { + "description": "The child's current foreground state, mirrored onto its parent association.\n\nOptional and nullable. Omitted means unchanged; `null` removes the\ncurrent report and leaves activity unconfirmed (not idle or cancelled).\nA concrete [`StateUpdate`] replaces the entire previous snapshot.", + "anyOf": [ + { + "$ref": "#/$defs/StateUpdate" + }, + { + "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": [ + "sessionId" + ] + }, + "SessionMessage": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAn upsert for an inter-session message.", "type": "object", "properties": { - "compactionId": { - "description": "The Agent-owned ID of this compaction, unique within the session.", + "messageId": { + "description": "Identifier of this message within the enclosing session's transcript.", "allOf": [ { - "$ref": "#/$defs/CompactionId" + "$ref": "#/$defs/MessageId" } ] }, - "status": { - "description": "Current lifecycle status.", - "allOf": [ + "senderSessionId": { + "description": "Optional sending session identity; omission or `null` retains a known value.", + "anyOf": [ { - "$ref": "#/$defs/CompactionStatus" + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" } - ] + ], + "x-deserialize-default-on-error": true }, - "summary": { - "description": "Complete replacement user-displayable summary retained by the compaction.", + "recipientSessionId": { + "description": "Optional receiving session identity; omission or `null` retains a known value.", + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "content": { + "description": "Omitted leaves content unchanged; `null` clears it; a concrete array\nreplaces the whole content collection.", "type": [ "array", "null" @@ -8588,16 +8849,8 @@ "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.", + "description": "Omitted leaves metadata unchanged; `null` clears it.\n\nImplementations MUST NOT make assumptions about values in `_meta`.", "type": [ "object", "null" @@ -8607,24 +8860,47 @@ } }, "required": [ - "compactionId", - "status" + "messageId" ] }, - "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.", + "SessionMessageChunk": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA streamed content block of an inter-session message.", "type": "object", "properties": { - "compactionId": { - "description": "ID of the compaction whose summary receives this content.", + "messageId": { + "description": "Identifier of this message within the enclosing session's transcript.", "allOf": [ { - "$ref": "#/$defs/CompactionId" + "$ref": "#/$defs/MessageId" } ] }, + "senderSessionId": { + "description": "Optional sending session identity; omission or `null` retains a known value.", + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "recipientSessionId": { + "description": "Optional receiving session identity; omission or `null` retains a known value.", + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, "content": { - "description": "One content block to append.", + "description": "A single content block appended to the message.", "allOf": [ { "$ref": "#/$defs/ContentBlock" @@ -8632,7 +8908,7 @@ ] }, "_meta": { - "description": "Metadata scoped to this chunk. Omission and `null` both mean absent.", + "description": "Optional and nullable chunk-scoped metadata; omitted or `null` means none.\n\nImplementations MUST NOT make assumptions about values in `_meta`.", "type": [ "object", "null" @@ -8642,7 +8918,7 @@ } }, "required": [ - "compactionId", + "messageId", "content" ] }, @@ -8674,48 +8950,6 @@ "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)" }, @@ -8894,15 +9128,6 @@ } ] }, - { - "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)", @@ -9603,7 +9828,7 @@ ] }, "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`.", + "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/message`.", "type": "object", "properties": { "name": { @@ -10786,24 +11011,6 @@ } ] }, - { - "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.", @@ -11162,50 +11369,84 @@ } } }, - "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" + "MessageMcpResponse": { + "description": "**UNSTABLE**\n\nThe successful outer ACP `mcp/message` response carries exactly one\ninner MCP outcome: an opaque result (including JSON null), or an MCP error.\nOuter ACP errors are reserved for binding and runtime failures.\n\nBoth branches require their carrier key. An error must be a non-null object.\nUnknown outer fields are ignored; inner result and error fields are preserved.\nCarrier `_meta` is optional; null or invalid values are treated as absent.\nSenders must include exactly one outcome; receivers prefer `result` if both are present.", + "anyOf": [ + { + "title": "Result", + "description": "An opaque inner MCP result.", + "type": "object", + "properties": { + "result": { + "description": "Required, even if JSON null." + }, + "_meta": { + "description": "Optional ACP carrier metadata.", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true } + }, + "required": [ + "result" ] }, - "_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 + { + "title": "Error", + "description": "A structured inner MCP error.", + "type": "object", + "properties": { + "error": { + "description": "Required, non-null MCP error object.", + "allOf": [ + { + "$ref": "#/$defs/McpError" + } + ] + }, + "_meta": { + "description": "Optional ACP carrier metadata.", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "error" + ] } - }, - "required": [ - "connectionId" ], "x-side": "client", - "x-method": "mcp/connect" + "x-method": "mcp/message" }, - "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`.", + "McpError": { + "description": "**UNSTABLE**\n\nAn inner MCP error, distinct from an outer ACP binding or runtime error.\n\n`code` and `message` are required and non-null. `data` is optional;\nexplicit `null` is preserved separately from an omitted key.", "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 + "code": { + "description": "Inner MCP error code; never an ACP error code.", + "type": "integer", + "format": "int32" + }, + "message": { + "description": "Inner MCP error message.", + "type": "string" + }, + "data": { + "description": "Optional error data; explicit null is retained." } }, - "x-side": "client", - "x-method": "mcp/disconnect" + "required": [ + "code", + "message" + ], + "additionalProperties": true }, "ClientNotification": { "description": "A JSON-RPC notification object.", @@ -11727,6 +11968,56 @@ } ] }, + "MessageMcpNotification": { + "description": "**UNSTABLE**\n\nNotification for an active request, sent from provider to consumer.\nIncludes subscription acknowledgements and updates.", + "type": "object", + "properties": { + "serverId": { + "description": "The declared ACP MCP server handling the associated request.", + "allOf": [ + { + "$ref": "#/$defs/McpServerAcpId" + } + ] + }, + "requestId": { + "description": "The identifier of the active inner MCP request.", + "allOf": [ + { + "$ref": "#/$defs/McpRequestId" + } + ] + }, + "method": { + "description": "The inner MCP method name.", + "type": "string" + }, + "params": { + "description": "Optional inner MCP params; null is equivalent to omission.", + "type": [ + "object", + "null" + ], + "additionalProperties": true + }, + "_meta": { + "description": "ACP extension metadata (not inner MCP params._meta); null is equivalent to omission.", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "serverId", + "requestId", + "method" + ], + "x-side": "agent", + "x-method": "mcp/message" + }, "ProtocolLevelNotification": { "description": "A JSON-RPC notification object.", "type": "object", diff --git a/scripts/gen_schema_v1.py b/scripts/gen_schema_v1.py index d2088076..fe655b9f 100644 --- a/scripts/gen_schema_v1.py +++ b/scripts/gen_schema_v1.py @@ -111,6 +111,8 @@ MODEL_NAME_MAP.update(variant_names) MODEL_NAME_MAP.update({ + inline_model_ref("MessageMcpResponse", ("anyOf", 0), ("object", None)): "McpResultResponse", + inline_model_ref("MessageMcpResponse", ("anyOf", 1), ("object", None)): "McpErrorResponse", inline_model_ref("RequestPermissionOutcome", ("oneOf", 0), ("object", None)): "DeniedOutcome", inline_model_ref("RequestPermissionOutcome", ("oneOf", 1), ("allOf", None)): "AllowedOutcome", inline_model_ref("ElicitationPropertySchema", ("anyOf", 5), ("object", None)): ("ElicitationOtherPropertySchema"), @@ -161,8 +163,10 @@ }) # datamodel-code-generator owns schema interpretation and its internal model names. -# This block only preserves the Python names already published by the SDK. +# Public aliases preserve published Python names and name the MCP outcome union. COMPATIBILITY_ALIASES = textwrap.dedent(""" + MessageMcpResponse = Annotated[Union[McpResultResponse, McpErrorResponse], Field(union_mode="left_to_right")] + PermissionOptionKind = Literal["allow_once", "allow_always", "reject_once", "reject_always"] PlanEntryPriority = Literal["high", "medium", "low"] PlanEntryStatus = Literal["pending", "in_progress", "completed"] @@ -230,6 +234,9 @@ class Jsonrpc(Enum): base_class="acp._schema_base.BaseModel", model_name_map=MODEL_NAME_MAP, compatibility_aliases=COMPATIBILITY_ALIASES, - # The generator loses additionalProperties types on nullable objects. - field_type_overrides={"ElicitationAcceptAction.content": "acp._schema_base.ElicitationContent"}, + # Preserve nullable object value types and reject non-integer MCP error codes. + field_type_overrides={ + "ElicitationAcceptAction.content": "acp._schema_base.ElicitationContent", + "McpError.code": "pydantic.StrictInt", + }, ) diff --git a/scripts/gen_schema_v2.py b/scripts/gen_schema_v2.py index eed4bcf1..980072d8 100644 --- a/scripts/gen_schema_v2.py +++ b/scripts/gen_schema_v2.py @@ -55,7 +55,7 @@ "StateUpdate", "anyOf", "allOf", - ("RunningState", "IdleState", "RequiresActionState"), + ("RunningState", "IdleState", "RequiresActionState", "UnknownState"), ), variant_model_map( "ToolCallContent", @@ -130,12 +130,17 @@ "SessionNotice", "SessionCompactionUpdate", "SessionCompactionSummaryChunk", + "SessionSubagentUpdate", + "SessionMessageUpdate", + "SessionMessageChunkUpdate", ), ), ): MODEL_NAME_MAP.update(variant_names) MODEL_NAME_MAP.update({ + inline_model_ref("MessageMcpResponse", ("anyOf", 0), ("object", None)): "McpResultResponse", + inline_model_ref("MessageMcpResponse", ("anyOf", 1), ("object", None)): "McpErrorResponse", 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", @@ -156,25 +161,27 @@ inline_model_ref("SetSessionConfigOptionRequest", ("anyOf", 2), ("object", None)): ( "SetSessionConfigOptionOtherRequest" ), - inline_model_ref("StateUpdate", ("anyOf", 3), ("object", None)): "OtherState", + inline_model_ref("StateUpdate", ("anyOf", 4), ("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", 20), ("object", None)): "OtherSessionUpdate", + inline_model_ref("SessionUpdate", ("anyOf", 23), ("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", 3), ("allOf", None)): "UnknownSessionStateUpdateBase", + inline_model_ref("SessionUpdate", ("anyOf", 6), ("allOf", 4), ("object", None)): ("OtherSessionStateUpdateBase"), inline_model_ref("SessionUpdate", ("anyOf", 6), ("allOf", None), ("allOf", None)): ("SessionStateUpdateBase"), }) for index, name in enumerate(( "RunningSessionStateUpdate", "IdleSessionStateUpdate", "RequiresActionSessionStateUpdate", + "UnknownSessionStateUpdate", "OtherSessionStateUpdate", )): MODEL_NAME_MAP[inline_model_ref("SessionUpdate", ("anyOf", 6), ("allOf", None), (f"union_model-{index}", None))] = ( @@ -229,7 +236,11 @@ version_file=ROOT / "schema" / "v2" / "VERSION", schema_out=ROOT / "src" / "acp" / "experimental" / "v2" / "schema.py", base_class="acp.experimental.v2._schema_base.BaseModel", + compatibility_aliases='MessageMcpResponse = Annotated[Union[McpResultResponse, McpErrorResponse], Field(union_mode="left_to_right")]', model_name_map=MODEL_NAME_MAP, - # The generator loses additionalProperties types on nullable objects. - field_type_overrides={"ElicitationAcceptAction.content": "acp._schema_base.ElicitationContent"}, + # Preserve nullable object value types and reject non-integer MCP error codes. + field_type_overrides={ + "ElicitationAcceptAction.content": "acp._schema_base.ElicitationContent", + "McpError.code": "pydantic.StrictInt", + }, ) diff --git a/src/acp/__init__.py b/src/acp/__init__.py index 02928a1b..ede36b13 100644 --- a/src/acp/__init__.py +++ b/src/acp/__init__.py @@ -22,8 +22,6 @@ CloseNesRequest, CloseNesResponse, CompleteElicitationNotification, - ConnectMcpRequest, - ConnectMcpResponse, CreateElicitationRequest, CreateElicitationResponse, CreateFormElicitationRequest, @@ -45,8 +43,6 @@ DidSaveDocumentNotification, DisableProviderRequest, DisableProviderResponse, - DisconnectMcpRequest, - DisconnectMcpResponse, ElicitationBooleanPropertySchema, ElicitationCapabilities, ElicitationFormCapabilities, @@ -72,8 +68,12 @@ LoadSessionResponse, LogoutRequest, LogoutResponse, + McpError, + McpErrorResponse, + McpResultResponse, MessageMcpNotification, MessageMcpRequest, + MessageMcpResponse, NewSessionRequest, NewSessionResponse, OtherElicitationResponse, @@ -129,8 +129,6 @@ "AcceptNesNotification", "CloseNesRequest", "CloseNesResponse", - "ConnectMcpRequest", - "ConnectMcpResponse", "DeleteSessionRequest", "DeleteSessionResponse", "DidChangeDocumentNotification", @@ -140,14 +138,16 @@ "DidSaveDocumentNotification", "DisableProviderRequest", "DisableProviderResponse", - "DisconnectMcpRequest", - "DisconnectMcpResponse", "ListProvidersRequest", "ListProvidersResponse", "LogoutRequest", "LogoutResponse", "MessageMcpNotification", "MessageMcpRequest", + "MessageMcpResponse", + "McpResultResponse", + "McpErrorResponse", + "McpError", "RejectNesNotification", "SetProviderRequest", "SetProviderResponse", diff --git a/src/acp/_mcp.py b/src/acp/_mcp.py new file mode 100644 index 00000000..8294c000 --- /dev/null +++ b/src/acp/_mcp.py @@ -0,0 +1,18 @@ +"""Validation of outgoing MCP outcomes, separate from ACP errors.""" + +from typing import Any + +from pydantic import BaseModel, TypeAdapter, ValidationError + +from .exceptions import RequestError + + +def validate_mcp_response(payload: Any, *, adapter: TypeAdapter[Any]) -> Any: + """Require exactly one outcome when sending; receivers may prefer result.""" + fields = type(payload).model_fields if isinstance(payload, BaseModel) else payload + if not isinstance(fields, dict) or (("result" in fields) == ("error" in fields)): + raise RequestError(-33002, "Invalid MCP response carrier: expected exactly one result or error") + try: + return adapter.validate_python(payload) + except ValidationError as exc: + raise RequestError(-33002, "Invalid MCP response carrier") from exc diff --git a/src/acp/_schema_base.py b/src/acp/_schema_base.py index 7719a015..c5a05fb9 100644 --- a/src/acp/_schema_base.py +++ b/src/acp/_schema_base.py @@ -21,6 +21,8 @@ class BaseModel(pydantic.BaseModel): """Runtime behavior shared by generated ACP schema models.""" + _preserved_null_fields: ClassVar[dict[str, str]] = {"McpResultResponse": "result", "McpError": "data"} + _reserved_tags: ClassVar[dict[str, tuple[str, frozenset[str]]]] = { "CreateOtherSessionElicitationRequest": ("mode", frozenset({"form", "url"})), "CreateOtherRequestElicitationRequest": ("mode", frozenset({"form", "url"})), @@ -49,6 +51,24 @@ def _include_literal_defaults( info: SerializationInfo, ) -> Any: data = handler(self) + # MCP preserves explicit null outcomes, error data, and opaque error extensions. + mcp_field = self._preserved_null_fields.get(type(self).__name__) + if ( + mcp_field is not None + and mcp_field in self.model_fields_set + and getattr(self, mcp_field) is None + and (info.include is None or mcp_field in info.include) + and (info.exclude is None or mcp_field not in info.exclude) + ): + data[mcp_field] = None + if type(self).__name__ == "McpError": + for name, value in (self.model_extra or {}).items(): + if ( + value is None + and (info.include is None or name in info.include) + and (info.exclude is None or name not in info.exclude) + ): + data[name] = None for name, field in type(self).model_fields.items(): annotation = field.annotation if info.include is not None and name not in info.include: diff --git a/src/acp/agent/connection.py b/src/acp/agent/connection.py index f0c793c8..9646fb0a 100644 --- a/src/acp/agent/connection.py +++ b/src/acp/agent/connection.py @@ -21,8 +21,6 @@ CancelElicitationResponse, CompleteElicitationNotification, ConfigOptionUpdate, - ConnectMcpRequest, - ConnectMcpResponse, CreateElicitationResponse, CreateFormElicitationRequest, CreateFormRequestElicitationRequest, @@ -34,8 +32,6 @@ CreateUrlSessionElicitationRequest, CurrentModeUpdate, DeclineElicitationResponse, - DisconnectMcpRequest, - DisconnectMcpResponse, ElicitationFormRequestMode, ElicitationFormSessionMode, ElicitationMode, @@ -44,8 +40,8 @@ EnvVariable, KillTerminalRequest, KillTerminalResponse, - MessageMcpNotification, MessageMcpRequest, + MessageMcpResponse, PermissionOption, ReadTextFileRequest, ReadTextFileResponse, @@ -58,6 +54,9 @@ SessionUpdateCompactionSummaryChunk, SessionUpdateCompactionUpdate, SessionUpdateNotice, + SessionUpdateSessionMessage, + SessionUpdateSessionMessageChunk, + SessionUpdateSubagentUpdate, TerminalOutputRequest, TerminalOutputResponse, ToolCallProgress, @@ -75,7 +74,6 @@ notify_model, param_model, request_model, - request_model_from_dict, request_optional_model, serialize_params, ) @@ -84,6 +82,7 @@ __all__ = ["AgentSideConnection"] _AGENT_CONNECTION_ERROR = "AgentSideConnection requires asyncio StreamWriter/StreamReader" _CREATE_ELICITATION_RESPONSE_ADAPTER = TypeAdapter(CreateElicitationResponse) +_MCP_RESPONSE_ADAPTER = TypeAdapter(MessageMcpResponse) @final @@ -167,7 +166,10 @@ async def session_update( | UsageUpdate | SessionUpdateNotice | SessionUpdateCompactionUpdate - | SessionUpdateCompactionSummaryChunk, + | SessionUpdateCompactionSummaryChunk + | SessionUpdateSubagentUpdate + | SessionUpdateSessionMessage + | SessionUpdateSessionMessageChunk, **kwargs: Any, ) -> None: await notify_model( @@ -292,46 +294,19 @@ async def complete_elicitation(self, elicitation_id: str, **kwargs: Any) -> None CompleteElicitationNotification(elicitation_id=elicitation_id, field_meta=kwargs or None), ) - @param_model(ConnectMcpRequest) - async def connect_mcp(self, server_id: str, **kwargs: Any) -> ConnectMcpResponse: - return await request_model( - self._conn, - CLIENT_METHODS["mcp_connect"], - ConnectMcpRequest(server_id=server_id, field_meta=kwargs or None), - ConnectMcpResponse, - ) - - @param_model(DisconnectMcpRequest) - async def disconnect_mcp(self, connection_id: str, **kwargs: Any) -> DisconnectMcpResponse: - return await request_model_from_dict( - self._conn, - CLIENT_METHODS["mcp_disconnect"], - DisconnectMcpRequest(connection_id=connection_id, field_meta=kwargs or None), - DisconnectMcpResponse, - ) - @param_model(MessageMcpRequest) async def mcp_message( - self, connection_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any - ) -> Any: - return await self._conn.send_request( + self, server_id: str, request_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any + ) -> MessageMcpResponse: + response = await self._conn.send_request( CLIENT_METHODS["mcp_message"], serialize_params( - MessageMcpRequest(connection_id=connection_id, method=method, params=params, field_meta=kwargs or None) - ), - ) - - @param_model(MessageMcpNotification) - async def notify_mcp( - self, connection_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any - ) -> None: - await notify_model( - self._conn, - CLIENT_METHODS["mcp_message"], - MessageMcpNotification( - connection_id=connection_id, method=method, params=params, field_meta=kwargs or None + MessageMcpRequest( + server_id=server_id, request_id=request_id, method=method, params=params, field_meta=kwargs or None + ) ), ) + return _MCP_RESPONSE_ADAPTER.validate_python(response) async def ext_method(self, method: str, params: dict[str, Any]) -> dict[str, Any]: return await self._conn.send_request(f"_{method}", params) diff --git a/src/acp/client/connection.py b/src/acp/client/connection.py index 3cd73d22..5135341a 100644 --- a/src/acp/client/connection.py +++ b/src/acp/client/connection.py @@ -50,7 +50,6 @@ LogoutResponse, McpServerStdio, MessageMcpNotification, - MessageMcpRequest, NesRepository, NesSuggestContext, NewSessionRequest, @@ -86,7 +85,6 @@ param_model, request_model, request_model_from_dict, - serialize_params, ) from .router import build_client_router @@ -434,26 +432,15 @@ async def logout(self, **kwargs: Any) -> LogoutResponse: self._conn, AGENT_METHODS["logout"], LogoutRequest(field_meta=kwargs or None), LogoutResponse ) - @param_model(MessageMcpRequest) - async def mcp_message( - self, connection_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any - ) -> Any: - return await self._conn.send_request( - AGENT_METHODS["mcp_message"], - serialize_params( - MessageMcpRequest(connection_id=connection_id, method=method, params=params, field_meta=kwargs or None) - ), - ) - @param_model(MessageMcpNotification) async def notify_mcp( - self, connection_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any + self, server_id: str, request_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any ) -> None: await notify_model( self._conn, AGENT_METHODS["mcp_message"], MessageMcpNotification( - connection_id=connection_id, method=method, params=params, field_meta=kwargs or None + server_id=server_id, request_id=request_id, method=method, params=params, field_meta=kwargs or None ), ) diff --git a/src/acp/experimental/v2/_methods.py b/src/acp/experimental/v2/_methods.py index 3ecd7876..f0d39516 100644 --- a/src/acp/experimental/v2/_methods.py +++ b/src/acp/experimental/v2/_methods.py @@ -1,5 +1,6 @@ from __future__ import annotations +from collections.abc import Callable from dataclasses import dataclass from functools import cache from typing import Any, get_type_hints @@ -16,6 +17,7 @@ class RequestSpec: request: TypeAdapter[Any] response: TypeAdapter[Any] empty_response: bool = False + adapt_result: Callable[[Any], Any] | None = None @dataclass(frozen=True, slots=True) @@ -48,6 +50,7 @@ def protocol_specs(protocol: type) -> tuple[tuple[RequestSpec, ...], tuple[Notif TypeAdapter(metadata.request_type), TypeAdapter(get_type_hints(handler, include_extras=True)["return"]), empty_response=metadata.default_result == {}, + adapt_result=metadata.adapt_result, ) return tuple(requests.values()), tuple(notifications.values()) diff --git a/src/acp/experimental/v2/_router.py b/src/acp/experimental/v2/_router.py index 4afb0e7e..4dddb537 100644 --- a/src/acp/experimental/v2/_router.py +++ b/src/acp/experimental/v2/_router.py @@ -41,6 +41,8 @@ async def handle_request(self, spec: RequestSpec, params: Any) -> Any: response = await handler(**model_to_kwargs(request, type(request))) if response is None and spec.empty_response: response = {} + if spec.adapt_result is not None: + response = spec.adapt_result(response) return spec.response.validate_python(response) async def handle_notification(self, spec: NotificationSpec, params: Any) -> None: diff --git a/src/acp/experimental/v2/_schema_base.py b/src/acp/experimental/v2/_schema_base.py index e2812efa..b63d4b32 100644 --- a/src/acp/experimental/v2/_schema_base.py +++ b/src/acp/experimental/v2/_schema_base.py @@ -20,7 +20,7 @@ class BaseModel(_BaseModel): "OtherPlanUpdateContent": ("type", frozenset({"file", "items", "markdown"})), "OtherReplayFrom": ("type", frozenset({"start"})), "OtherSessionConfigOption": ("type", frozenset({"boolean", "select"})), - "OtherSessionStateUpdate": ("state", frozenset({"idle", "requires_action", "running"})), + "OtherSessionStateUpdate": ("state", frozenset({"idle", "requires_action", "running", "unknown"})), "OtherSessionUpdate": ( "sessionUpdate", frozenset({ @@ -44,9 +44,12 @@ class BaseModel(_BaseModel): "usage_update", "user_message", "user_message_chunk", + "subagent_update", + "session_message", + "session_message_chunk", }), ), - "OtherState": ("state", frozenset({"idle", "requires_action", "running"})), + "OtherState": ("state", frozenset({"idle", "requires_action", "running", "unknown"})), "OtherToolCallContent": ("type", frozenset({"content", "diff", "terminal"})), "SetSessionConfigOptionOtherRequest": ("type", frozenset({"boolean", "id"})), "CreateOtherSessionElicitationRequest": ("mode", frozenset({"form", "url"})), diff --git a/src/acp/experimental/v2/agent.py b/src/acp/experimental/v2/agent.py index 4eaf2f05..ab829105 100644 --- a/src/acp/experimental/v2/agent.py +++ b/src/acp/experimental/v2/agent.py @@ -12,9 +12,7 @@ from . import schema from ._connection import open_connection from ._initialization import InitializationState -from ._methods import ( - CLIENT_REQUESTS_BY_METHOD, -) +from ._methods import CLIENT_REQUESTS_BY_METHOD from ._params import build_elicitation_request, build_request from ._router import MethodRouter from .interfaces import Agent, CreateElicitationRequest, CreateElicitationResponse @@ -143,10 +141,14 @@ async def session_update( | schema.SessionNotice | schema.SessionCompactionUpdate | schema.SessionCompactionSummaryChunk + | schema.SessionSubagentUpdate + | schema.SessionMessageUpdate + | schema.SessionMessageChunkUpdate | schema.OtherSessionUpdate | schema.RunningSessionStateUpdate | schema.IdleSessionStateUpdate | schema.RequiresActionSessionStateUpdate + | schema.UnknownSessionStateUpdate | schema.OtherSessionStateUpdate, **kwargs: Any, ) -> None: @@ -155,43 +157,19 @@ async def session_update( build_request(schema.UpdateSessionNotification, {"session_id": session_id, "update": update}, kwargs), ) - @param_model(schema.ConnectMcpRequest) - async def connect_mcp(self, server_id: str, **kwargs: Any) -> schema.ConnectMcpResponse: - return await self._request( - CLIENT_METHODS["mcp_connect"], build_request(schema.ConnectMcpRequest, {"server_id": server_id}, kwargs) - ) - @param_model(schema.MessageMcpRequest) async def mcp_message( - self, connection_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any - ) -> Any: + self, server_id: str, request_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any + ) -> schema.MessageMcpResponse: return await self._request( CLIENT_METHODS["mcp_message"], build_request( - schema.MessageMcpRequest, {"connection_id": connection_id, "method": method, "params": params}, kwargs - ), - ) - - @param_model(schema.MessageMcpNotification) - async def notify_mcp( - self, connection_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any - ) -> None: - await self._notify( - CLIENT_METHODS["mcp_message"], - build_request( - schema.MessageMcpNotification, - {"connection_id": connection_id, "method": method, "params": params}, + schema.MessageMcpRequest, + {"server_id": server_id, "request_id": request_id, "method": method, "params": params}, kwargs, ), ) - @param_model(schema.DisconnectMcpRequest) - async def disconnect_mcp(self, connection_id: str, **kwargs: Any) -> schema.DisconnectMcpResponse: - return await self._request( - CLIENT_METHODS["mcp_disconnect"], - build_request(schema.DisconnectMcpRequest, {"connection_id": connection_id}, kwargs), - ) - @param_model(CreateElicitationRequest) async def create_elicitation( self, diff --git a/src/acp/experimental/v2/client.py b/src/acp/experimental/v2/client.py index ce82acd0..2db21aea 100644 --- a/src/acp/experimental/v2/client.py +++ b/src/acp/experimental/v2/client.py @@ -247,26 +247,15 @@ async def cancel_session(self, session_id: str, **kwargs: Any) -> None: build_request(schema.CancelSessionNotification, {"session_id": session_id}, kwargs), ) - @param_model(schema.MessageMcpRequest) - async def mcp_message( - self, connection_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any - ) -> Any: - return await self._request( - AGENT_METHODS["mcp_message"], - build_request( - schema.MessageMcpRequest, {"connection_id": connection_id, "method": method, "params": params}, kwargs - ), - ) - @param_model(schema.MessageMcpNotification) async def notify_mcp( - self, connection_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any + self, server_id: str, request_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any ) -> None: await self._notify( AGENT_METHODS["mcp_message"], build_request( schema.MessageMcpNotification, - {"connection_id": connection_id, "method": method, "params": params}, + {"server_id": server_id, "request_id": request_id, "method": method, "params": params}, kwargs, ), ) diff --git a/src/acp/experimental/v2/interfaces.py b/src/acp/experimental/v2/interfaces.py index 36692e16..f5b84955 100644 --- a/src/acp/experimental/v2/interfaces.py +++ b/src/acp/experimental/v2/interfaces.py @@ -1,9 +1,11 @@ from __future__ import annotations +from functools import partial from typing import Any, Literal, Protocol -from pydantic import AnyUrl +from pydantic import AnyUrl, TypeAdapter +from acp._mcp import validate_mcp_response from acp.utils import param_model from . import schema @@ -14,7 +16,6 @@ | schema.SetSessionConfigOptionBooleanRequest | schema.SetSessionConfigOptionOtherRequest ) - CreateElicitationRequest = ( schema.CreateOtherSessionElicitationRequest | schema.CreateOtherRequestElicitationRequest @@ -23,7 +24,6 @@ | schema.CreateUrlSessionElicitationRequest | schema.CreateUrlRequestElicitationRequest ) - CreateElicitationResponse = ( schema.AcceptElicitationResponse | schema.DeclineElicitationResponse @@ -144,14 +144,9 @@ async def prompt( @param_model(schema.CancelSessionNotification, method=AGENT_METHODS["session_cancel"], kind="notification") async def cancel_session(self, session_id: str, **kwargs: Any) -> None: ... - @param_model(schema.MessageMcpRequest, method=AGENT_METHODS["mcp_message"]) - async def mcp_message( - self, connection_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any - ) -> Any: ... - @param_model(schema.MessageMcpNotification, method=AGENT_METHODS["mcp_message"], kind="notification") async def notify_mcp( - self, connection_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any + self, server_id: str, request_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any ) -> None: ... @param_model(schema.StartNesRequest, method=AGENT_METHODS["nes_start"]) @@ -269,29 +264,26 @@ async def session_update( | schema.SessionNotice | schema.SessionCompactionUpdate | schema.SessionCompactionSummaryChunk + | schema.SessionSubagentUpdate + | schema.SessionMessageUpdate + | schema.SessionMessageChunkUpdate | schema.OtherSessionUpdate | schema.RunningSessionStateUpdate | schema.IdleSessionStateUpdate | schema.RequiresActionSessionStateUpdate + | schema.UnknownSessionStateUpdate | schema.OtherSessionStateUpdate, **kwargs: Any, ) -> None: ... - @param_model(schema.ConnectMcpRequest, method=CLIENT_METHODS["mcp_connect"]) - async def connect_mcp(self, server_id: str, **kwargs: Any) -> schema.ConnectMcpResponse: ... - - @param_model(schema.MessageMcpRequest, method=CLIENT_METHODS["mcp_message"]) + @param_model( + schema.MessageMcpRequest, + method=CLIENT_METHODS["mcp_message"], + adapt_result=partial(validate_mcp_response, adapter=TypeAdapter(schema.MessageMcpResponse)), + ) async def mcp_message( - self, connection_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any - ) -> Any: ... - - @param_model(schema.MessageMcpNotification, method=CLIENT_METHODS["mcp_message"], kind="notification") - async def notify_mcp( - self, connection_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any - ) -> None: ... - - @param_model(schema.DisconnectMcpRequest, method=CLIENT_METHODS["mcp_disconnect"], default_result={}) - async def disconnect_mcp(self, connection_id: str, **kwargs: Any) -> schema.DisconnectMcpResponse: ... + self, server_id: str, request_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any + ) -> schema.MessageMcpResponse: ... @param_model(CreateElicitationRequest, method=CLIENT_METHODS["elicitation_create"]) async def create_elicitation( diff --git a/src/acp/experimental/v2/meta.py b/src/acp/experimental/v2/meta.py index 76bbadce..2f2ce75b 100644 --- a/src/acp/experimental/v2/meta.py +++ b/src/acp/experimental/v2/meta.py @@ -1,5 +1,5 @@ # Generated from schema/v2/meta.json. Do not edit by hand. -# Schema ref: refs/tags/schema-v2.0.0-alpha.5 +# Schema ref: refs/tags/schema-v2.0.0-alpha.7 AGENT_METHODS = { "initialize": "initialize", "auth_login": "auth/login", @@ -31,9 +31,7 @@ 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", } diff --git a/src/acp/experimental/v2/schema.py b/src/acp/experimental/v2/schema.py index 0baa59fe..801771be 100644 --- a/src/acp/experimental/v2/schema.py +++ b/src/acp/experimental/v2/schema.py @@ -1,5 +1,5 @@ # Generated from schema/v2/schema.json. Do not edit by hand. -# Schema ref: refs/tags/schema-v2.0.0-alpha.5 +# Schema ref: refs/tags/schema-v2.0.0-alpha.7 from __future__ import annotations @@ -15,6 +15,7 @@ ConfigDict, Field, RootModel, + StrictInt, ValidationInfo, ValidatorFunctionWrapHandler, field_validator, @@ -600,21 +601,6 @@ class ElicitationUrlMode(RootModel[Union[ElicitationUrlSessionMode, ElicitationU """ -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 """ @@ -1097,6 +1083,35 @@ class SessionConfigBoolean(BaseModel): """ +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 SessionInfo(BaseModel): session_id: Annotated[str, Field(alias="sessionId")] """ @@ -1434,6 +1449,15 @@ class RequiresActionStateUpdate(BaseModel): """ +class UnknownStateUpdate(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + The _meta property is reserved by ACP for additional metadata. + Implementations MUST NOT make assumptions about values at these keys. + Optional; omitted and `null` mean no metadata for this state snapshot. + """ + + class RunningState(RunningStateUpdate): state: Literal["running"] = "running" @@ -1446,6 +1470,10 @@ class RequiresActionState(RequiresActionStateUpdate): state: Literal["requires_action"] = "requires_action" +class UnknownState(UnknownStateUpdate): + state: Literal["unknown"] = "unknown" + + class OtherState(BaseModel): model_config = ConfigDict( extra="allow", @@ -1460,16 +1488,6 @@ class OtherState(BaseModel): """ -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"})] """ @@ -1624,35 +1642,6 @@ class PlanRemoved(BaseModel): """ -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 """ @@ -1742,37 +1731,21 @@ def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHa return use_default_on_error(v, handler, info) -class CompleteElicitationNotification(BaseModel): - elicitation_id: Annotated[str, Field(alias="elicitationId")] - """ - The ID of the elicitation that completed. - """ +class SessionCancelCapabilities(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 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 +class CompleteElicitationNotification(BaseModel): + elicitation_id: Annotated[str, Field(alias="elicitationId")] """ - Optional inner MCP params. - - If omitted or set to `null`, the inner MCP message has no params. + The ID of the elicitation that completed. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -1780,14 +1753,11 @@ class MessageMcpNotification(BaseModel): 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("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 @@ -2460,29 +2430,32 @@ class ElicitationAcceptAction(BaseModel): """ -class ConnectMcpResponse(BaseModel): - connection_id: Annotated[str, Field(alias="connectionId")] +class McpResultResponse(BaseModel): + result: Any """ - The unique identifier for this MCP-over-ACP connection. + Required, even if JSON null. """ 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) + Optional ACP carrier metadata. """ -class DisconnectMcpResponse(BaseModel): - field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None +class McpError(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + code: StrictInt """ - The _meta property is reserved 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) + Inner MCP error code; never an ACP error code. + """ + message: str + """ + Inner MCP error message. + """ + data: Optional[Any] = None + """ + Optional error data; explicit null is retained. """ @@ -2589,6 +2562,29 @@ class AcceptNesNotification(BaseModel): """ +class MessageMcpNotification(BaseModel): + server_id: Annotated[str, Field(alias="serverId")] + """ + The declared ACP MCP server handling the associated request. + """ + request_id: Annotated[str, Field(alias="requestId")] + """ + The identifier of the active inner MCP request. + """ + method: str + """ + The inner MCP method name. + """ + params: Optional[Dict[str, Any]] = None + """ + Optional inner MCP params; null is equivalent to omission. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + ACP extension metadata (not inner MCP params._meta); null is equivalent to omission. + """ + + class CancelRequestNotification(BaseModel): request_id: Annotated[Optional[Union[int, str]], Field(alias="requestId")] """ @@ -3274,25 +3270,14 @@ def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHand return skip_invalid_items(v, handler, info) -class ConnectMcpRequest(BaseModel): +class MessageMcpRequest(BaseModel): server_id: Annotated[str, Field(alias="serverId")] """ - The ACP MCP server ID that was provided by the component declaring the MCP server. + The declared ACP MCP server receiving this request. """ - field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + request_id: Annotated[str, Field(alias="requestId")] """ - The _meta property is reserved 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. + The caller-generated identifier for the inner MCP request. """ method: str """ @@ -3300,17 +3285,11 @@ class MessageMcpRequest(BaseModel): """ params: Optional[Dict[str, Any]] = None """ - Optional inner MCP params. - - If omitted or set to `null`, the inner MCP message has no params. + Optional inner MCP params; null is equivalent to omission. """ 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) + ACP extension metadata (not inner MCP params._meta); null is equivalent to omission. """ @@ -3628,6 +3607,10 @@ def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHand return skip_invalid_items(v, handler, info) +class TextAvailableCommandInput(TextCommandInput): + type: Literal["text"] = "text" + + class ListSessionsResponse(BaseModel): sessions: List[SessionInfo] """ @@ -3773,6 +3756,10 @@ class RequiresActionSessionStateUpdateBase(RequiresActionStateUpdate): state: Literal["requires_action"] = "requires_action" +class UnknownSessionStateUpdateBase(UnknownStateUpdate): + state: Literal["unknown"] = "unknown" + + class RunningSessionStateUpdate(RunningSessionStateUpdateBase, SessionStateUpdateBase): session_update: Annotated[Literal["state_update"], Field(alias="sessionUpdate")] = "state_update" @@ -3785,6 +3772,10 @@ class RequiresActionSessionStateUpdate(RequiresActionSessionStateUpdateBase, Ses session_update: Annotated[Literal["state_update"], Field(alias="sessionUpdate")] = "state_update" +class UnknownSessionStateUpdate(UnknownSessionStateUpdateBase, 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" @@ -3896,8 +3887,73 @@ def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHand return skip_invalid_items(v, handler, info) -class TextAvailableCommandInput(TextCommandInput): - type: Literal["text"] = "text" +class SubagentSessionCapabilities(BaseModel): + cancel: Optional[SessionCancelCapabilities] = None + """ + Permits the client to cancel this child's current work without ending + the session. Omitted or `null` means unsupported; an object (including + `{}`) means supported. + """ + 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. + """ + + @field_validator("cancel", 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 SubagentUpdate(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The opaque session ID identifying the child in all ACP messages. + """ + title: Optional[str] = None + """ + The parent's human-readable display title for this child. It need not be unique. + + Optional and nullable. Omitted means unchanged; `null` clears it. If no + title is set, the Client chooses a fallback presentation. + """ + description: Optional[str] = None + """ + The parent's human-readable description of the child's role or purpose. + + Optional and nullable. Omitted means unchanged; `null` clears it. This is + current display metadata, not the history of instructions sent to the child. + """ + capabilities: Optional[SubagentSessionCapabilities] = None + """ + Client-initiated session mutations permitted for this subagent session. + + Read-only operations retain their normal protocol semantics and + capability requirements. + """ + state: Optional[Union[RunningState, IdleState, RequiresActionState, UnknownState, OtherState]] = None + """ + The child's current foreground state, mirrored onto its parent association. + + Optional and nullable. Omitted means unchanged; `null` removes the + current report and leaves activity unconfirmed (not idle or cancelled). + A concrete [`StateUpdate`] replaces the entire previous snapshot. + """ + 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("capabilities", "description", "state", "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 AuthCapabilities(BaseModel): @@ -4174,6 +4230,17 @@ class AcceptElicitationResponse(ElicitationAcceptAction): action: Literal["accept"] = "accept" +class McpErrorResponse(BaseModel): + error: McpError + """ + Required, non-null MCP error object. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + Optional ACP carrier metadata. + """ + + class TextDocumentContentChangeEvent(BaseModel): range: Optional[Range] = None """ @@ -4450,6 +4517,34 @@ class SessionConfigSelect(BaseModel): """ +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 NesTextEdit(BaseModel): range: Range """ @@ -4501,6 +4596,10 @@ def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHa return use_default_on_error(v, handler, info) +class SessionSubagentUpdate(SubagentUpdate): + session_update: Annotated[Literal["subagent_update"], Field(alias="sessionUpdate")] = "subagent_update" + + class ContentChunk(BaseModel): message_id: Annotated[str, Field(alias="messageId")] """ @@ -4654,34 +4753,6 @@ class PlanUpdate(BaseModel): """ -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")] """ @@ -4763,6 +4834,90 @@ class CompactionSummaryChunk(BaseModel): """ +class SessionMessage(BaseModel): + message_id: Annotated[str, Field(alias="messageId")] + """ + Identifier of this message within the enclosing session's transcript. + """ + sender_session_id: Annotated[Optional[str], Field(alias="senderSessionId")] = None + """ + Optional sending session identity; omission or `null` retains a known value. + """ + recipient_session_id: Annotated[Optional[str], Field(alias="recipientSessionId")] = None + """ + Optional receiving session identity; omission or `null` retains a known value. + """ + content: Optional[ + List[ + Union[ + TextContentBlock, + ImageContentBlock, + AudioContentBlock, + ResourceContentBlock, + EmbeddedResourceContentBlock, + OtherContentBlock, + ] + ] + ] = None + """ + Omitted leaves content unchanged; `null` clears it; a concrete array + replaces the whole content collection. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + Omitted leaves metadata unchanged; `null` clears it. + + Implementations MUST NOT make assumptions about values in `_meta`. + """ + + @field_validator("recipient_session_id", "sender_session_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) + + @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 SessionMessageChunk(BaseModel): + message_id: Annotated[str, Field(alias="messageId")] + """ + Identifier of this message within the enclosing session's transcript. + """ + sender_session_id: Annotated[Optional[str], Field(alias="senderSessionId")] = None + """ + Optional sending session identity; omission or `null` retains a known value. + """ + recipient_session_id: Annotated[Optional[str], Field(alias="recipientSessionId")] = None + """ + Optional receiving session identity; omission or `null` retains a known value. + """ + content: Union[ + TextContentBlock, + ImageContentBlock, + AudioContentBlock, + ResourceContentBlock, + EmbeddedResourceContentBlock, + OtherContentBlock, + ] + """ + A single content block appended to the message. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + Optional and nullable chunk-scoped metadata; omitted or `null` means none. + + Implementations MUST NOT make assumptions about values in `_meta`. + """ + + @field_validator("recipient_session_id", "sender_session_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 ClientCapabilities(BaseModel): auth: Optional[AuthCapabilities] = None """ @@ -5178,6 +5333,14 @@ class ForkSessionResponse(BaseModel): """ Initial session configuration options. """ + available_commands: Annotated[Optional[List[AvailableCommand]], Field(alias="availableCommands")] = None + """ + Initial commands the agent can execute in this session. + + Optional. Omitted or empty means no initial commands are advertised. + Senders MUST use an array, not `null`; receivers treat `null` like omission. + Later `available_commands_update` notifications replace this list. + """ 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 @@ -5187,7 +5350,7 @@ class ForkSessionResponse(BaseModel): See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) """ - @field_validator("config_options", mode="wrap") + @field_validator("available_commands", "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) @@ -5201,6 +5364,14 @@ class ResumeSessionResponse(BaseModel): """ Initial session configuration options. """ + available_commands: Annotated[Optional[List[AvailableCommand]], Field(alias="availableCommands")] = None + """ + Initial commands the agent can execute in this session. + + Optional. Omitted or empty means no initial commands are advertised. + Senders MUST use an array, not `null`; receivers treat `null` like omission. + Later `available_commands_update` notifications replace this list. + """ 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 @@ -5210,7 +5381,7 @@ class ResumeSessionResponse(BaseModel): See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) """ - @field_validator("config_options", mode="wrap") + @field_validator("available_commands", "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) @@ -5292,6 +5463,14 @@ class SessionCompactionSummaryChunk(CompactionSummaryChunk): ) +class SessionMessageUpdate(SessionMessage): + session_update: Annotated[Literal["session_message"], Field(alias="sessionUpdate")] = "session_message" + + +class SessionMessageChunkUpdate(SessionMessageChunk): + session_update: Annotated[Literal["session_message_chunk"], Field(alias="sessionUpdate")] = "session_message_chunk" + + class ToolCallContentChunk(BaseModel): tool_call_id: Annotated[str, Field(alias="toolCallId")] """ @@ -5410,12 +5589,10 @@ class ClientResponseMessage(BaseModel): """ result: Union[ RequestPermissionResponse, - ConnectMcpResponse, - DisconnectMcpResponse, - AcceptElicitationResponse, - DeclineElicitationResponse, - CancelElicitationResponse, - OtherElicitationResponse, + Union[ + AcceptElicitationResponse, DeclineElicitationResponse, CancelElicitationResponse, OtherElicitationResponse + ], + Union[McpResultResponse, McpErrorResponse], Any, ] """ @@ -5638,6 +5815,14 @@ class NewSessionResponse(BaseModel): """ Initial session configuration options. """ + available_commands: Annotated[Optional[List[AvailableCommand]], Field(alias="availableCommands")] = None + """ + Initial commands the agent can execute in this session. + + Optional. Omitted or empty means no initial commands are advertised. + Senders MUST use an array, not `null`; receivers treat `null` like omission. + Later `available_commands_update` notifications replace this list. + """ 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 @@ -5647,7 +5832,7 @@ class NewSessionResponse(BaseModel): See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) """ - @field_validator("config_options", mode="wrap") + @field_validator("available_commands", "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) @@ -5722,10 +5907,11 @@ class ClientRequest(BaseModel): StartNesRequest, SuggestNesRequest, CloseNesRequest, - MessageMcpRequest, - SetSessionConfigOptionIdRequest, - SetSessionConfigOptionBooleanRequest, - SetSessionConfigOptionOtherRequest, + Union[ + SetSessionConfigOptionIdRequest, + SetSessionConfigOptionBooleanRequest, + SetSessionConfigOptionOtherRequest, + ], Any, ] ] = None @@ -5827,11 +6013,17 @@ class UpdateSessionNotification(BaseModel): SessionNotice, SessionCompactionUpdate, SessionCompactionSummaryChunk, + SessionSubagentUpdate, + SessionMessageUpdate, + SessionMessageChunkUpdate, OtherSessionUpdate, - RunningSessionStateUpdate, - IdleSessionStateUpdate, - RequiresActionSessionStateUpdate, - OtherSessionStateUpdate, + Union[ + RunningSessionStateUpdate, + IdleSessionStateUpdate, + RequiresActionSessionStateUpdate, + UnknownSessionStateUpdate, + OtherSessionStateUpdate, + ], ] """ The actual update content. @@ -5945,9 +6137,7 @@ class AgentNotification(BaseModel): """ The notification method name. """ - params: Optional[Union[UpdateSessionNotification, CompleteElicitationNotification, MessageMcpNotification, Any]] = ( - None - ) + params: Optional[Union[UpdateSessionNotification, CompleteElicitationNotification, Any]] = None """ Method-specific notification parameters. """ @@ -5965,15 +6155,12 @@ class AgentRequest(BaseModel): params: Optional[ Union[ RequestPermissionRequest, - ConnectMcpRequest, MessageMcpRequest, - DisconnectMcpRequest, - CreateOtherSessionElicitationRequest, - CreateOtherRequestElicitationRequest, - CreateFormSessionElicitationRequest, - CreateFormRequestElicitationRequest, - CreateUrlSessionElicitationRequest, - CreateUrlRequestElicitationRequest, + Union[ + Union[CreateOtherSessionElicitationRequest, CreateOtherRequestElicitationRequest], + Union[CreateFormSessionElicitationRequest, CreateFormRequestElicitationRequest], + Union[CreateUrlSessionElicitationRequest, CreateUrlRequestElicitationRequest], + ], Any, ] ] = None @@ -6017,3 +6204,6 @@ class AgentResponse(RootModel[Union[AgentResponseMessage, AgentErrorMessage]]): """ A JSON-RPC response object. """ + + +MessageMcpResponse = Annotated[Union[McpResultResponse, McpErrorResponse], Field(union_mode="left_to_right")] diff --git a/src/acp/interfaces.py b/src/acp/interfaces.py index 073f5166..d4641f9b 100644 --- a/src/acp/interfaces.py +++ b/src/acp/interfaces.py @@ -1,7 +1,11 @@ from __future__ import annotations +from functools import partial from typing import Any, Literal, Protocol +from pydantic import TypeAdapter + +from ._mcp import validate_mcp_response from ._protocol_adapters import ( elicitation_to_kwargs, validate_create_elicitation_request, @@ -28,8 +32,6 @@ CloseSessionResponse, CompleteElicitationNotification, ConfigOptionUpdate, - ConnectMcpRequest, - ConnectMcpResponse, CreateElicitationResponse, CreateFormRequestElicitationRequest, CreateFormSessionElicitationRequest, @@ -47,8 +49,6 @@ DidSaveDocumentNotification, DisableProviderRequest, DisableProviderResponse, - DisconnectMcpRequest, - DisconnectMcpResponse, ElicitationMode, EmbeddedResourceContentBlock, EnvVariable, @@ -72,6 +72,7 @@ McpServerStdio, MessageMcpNotification, MessageMcpRequest, + MessageMcpResponse, NesRepository, NesSuggestContext, NewSessionRequest, @@ -96,6 +97,9 @@ SessionUpdateCompactionSummaryChunk, SessionUpdateCompactionUpdate, SessionUpdateNotice, + SessionUpdateSessionMessage, + SessionUpdateSessionMessageChunk, + SessionUpdateSubagentUpdate, SetProviderRequest, SetProviderResponse, SetSessionConfigOptionBooleanRequest, @@ -129,23 +133,15 @@ class Client(Protocol): - @param_model(ConnectMcpRequest, method=CLIENT_METHODS["mcp_connect"], unstable=True) - async def connect_mcp(self, server_id: str, **kwargs: Any) -> ConnectMcpResponse: ... - @param_model( - DisconnectMcpRequest, method=CLIENT_METHODS["mcp_disconnect"], unstable=True, adapt_result=normalize_result + MessageMcpRequest, + method=CLIENT_METHODS["mcp_message"], + unstable=True, + adapt_result=partial(validate_mcp_response, adapter=TypeAdapter(MessageMcpResponse)), ) - async def disconnect_mcp(self, connection_id: str, **kwargs: Any) -> DisconnectMcpResponse: ... - - @param_model(MessageMcpRequest, method=CLIENT_METHODS["mcp_message"], unstable=True) async def mcp_message( - self, connection_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any - ) -> Any: ... - - @param_model(MessageMcpNotification, method=CLIENT_METHODS["mcp_message"], kind="notification", unstable=True) - async def notify_mcp( - self, connection_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any - ) -> None: ... + self, server_id: str, request_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any + ) -> MessageMcpResponse: ... @param_model(RequestPermissionRequest, method=CLIENT_METHODS["session_request_permission"]) async def request_permission( @@ -171,7 +167,10 @@ async def session_update( | UsageUpdate | SessionUpdateNotice | SessionUpdateCompactionUpdate - | SessionUpdateCompactionSummaryChunk, + | SessionUpdateCompactionSummaryChunk + | SessionUpdateSubagentUpdate + | SessionUpdateSessionMessage + | SessionUpdateSessionMessageChunk, **kwargs: Any, ) -> None: ... @@ -289,14 +288,9 @@ async def disable_provider(self, provider_id: str, **kwargs: Any) -> DisableProv @param_model(LogoutRequest, method=AGENT_METHODS["logout"], adapt_result=normalize_result) async def logout(self, **kwargs: Any) -> LogoutResponse: ... - @param_model(MessageMcpRequest, method=AGENT_METHODS["mcp_message"], unstable=True) - async def mcp_message( - self, connection_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any - ) -> Any: ... - @param_model(MessageMcpNotification, method=AGENT_METHODS["mcp_message"], kind="notification", unstable=True) async def notify_mcp( - self, connection_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any + self, server_id: str, request_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any ) -> None: ... @param_model(StartNesRequest, method=AGENT_METHODS["nes_start"], unstable=True) diff --git a/src/acp/meta.py b/src/acp/meta.py index 0c1565ae..9960944a 100644 --- a/src/acp/meta.py +++ b/src/acp/meta.py @@ -1,5 +1,5 @@ # Generated from schema/meta.json. Do not edit by hand. -# Schema ref: refs/tags/schema-v1.23.0 +# Schema ref: refs/tags/schema-v1.24.1 AGENT_METHODS = { "initialize": "initialize", "authenticate": "authenticate", @@ -40,9 +40,7 @@ "terminal_release": "terminal/release", "terminal_wait_for_exit": "terminal/wait_for_exit", "terminal_kill": "terminal/kill", - "mcp_connect": "mcp/connect", "mcp_message": "mcp/message", - "mcp_disconnect": "mcp/disconnect", "elicitation_create": "elicitation/create", "elicitation_complete": "elicitation/complete", } diff --git a/src/acp/schema.py b/src/acp/schema.py index c47eb0d2..9ee274f5 100644 --- a/src/acp/schema.py +++ b/src/acp/schema.py @@ -1,5 +1,5 @@ # Generated from schema/schema.json. Do not edit by hand. -# Schema ref: refs/tags/schema-v1.23.0 +# Schema ref: refs/tags/schema-v1.24.1 from __future__ import annotations @@ -8,7 +8,16 @@ from acp._deserialize import coerce_protocol_version, skip_invalid_items, use_default_on_error from acp._schema_base import BaseModel, ElicitationContent -from pydantic import AnyUrl, ConfigDict, Field, RootModel, ValidationInfo, ValidatorFunctionWrapHandler, field_validator +from pydantic import ( + AnyUrl, + ConfigDict, + Field, + RootModel, + StrictInt, + ValidationInfo, + ValidatorFunctionWrapHandler, + field_validator, +) class ReadTextFileRequest(BaseModel): @@ -650,21 +659,6 @@ class ElicitationUrlMode(RootModel[Union[ElicitationUrlSessionMode, ElicitationU """ -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/extensibility) - """ - - class PromptCapabilities(BaseModel): image: Optional[bool] = False """ @@ -1601,37 +1595,85 @@ def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHa return use_default_on_error(v, handler, info) -class CompleteElicitationNotification(BaseModel): - elicitation_id: Annotated[str, Field(alias="elicitationId")] - """ - The ID of the elicitation that completed. - """ +class SessionCancelCapabilities(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/extensibility) """ -class MessageMcpNotification(BaseModel): - connection_id: Annotated[str, Field(alias="connectionId")] +class StateUpdate5(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + state: str """ - The MCP-over-ACP connection this message is sent on. + Unrecognized state discriminator. """ - method: str + + +class RunningStateUpdate(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ - The inner MCP method name. + The _meta property is reserved by ACP for additional metadata. + Implementations MUST NOT make assumptions about values at these keys. + Optional; omitted and `null` mean no metadata for this state snapshot. """ - params: Optional[Dict[str, Any]] = None + + +class IdleStateUpdate(BaseModel): + stop_reason: Annotated[ + Optional[Literal["end_turn", "max_tokens", "max_turn_requests", "refusal", "cancelled"]], + Field(alias="stopReason"), + ] = None """ - Optional inner MCP params. + Reason foreground work stopped. Optional; omitted or `null` means not reported. + """ + usage: Optional[Usage] = None + """ + **UNSTABLE** Token usage for completed foreground work. - If omitted or set to `null`, the inner MCP message has no params. + Optional; omitted or `null` means not reported. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + The _meta property is reserved by ACP for additional metadata. + Implementations MUST NOT make assumptions about values at these keys. + Optional; omitted and `null` mean no metadata for this state snapshot. + """ + + @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 for additional metadata. + Implementations MUST NOT make assumptions about values at these keys. + Optional; omitted and `null` mean no metadata for this state snapshot. + """ + + +class UnknownStateUpdate(BaseModel): + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + The _meta property is reserved by ACP for additional metadata. + Implementations MUST NOT make assumptions about values at these keys. + Optional; omitted and `null` mean no metadata for this state snapshot. + """ + + +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 """ @@ -1639,14 +1681,11 @@ class MessageMcpNotification(BaseModel): 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/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 FileSystemCapabilities(BaseModel): read_text_file: Annotated[Optional[bool], Field(alias="readTextFile")] = False @@ -1691,6 +1730,15 @@ class NoticeCapabilities(BaseModel): pass +class SubagentCapabilities(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. + """ + + class PlanCapabilities(BaseModel): field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -2443,29 +2491,32 @@ class ElicitationAcceptAction(BaseModel): """ -class ConnectMcpResponse(BaseModel): - connection_id: Annotated[str, Field(alias="connectionId")] +class McpResultResponse(BaseModel): + result: Any """ - The unique identifier for this MCP-over-ACP connection. + Required, even if JSON null. """ 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/extensibility) + Optional ACP carrier metadata. """ -class DisconnectMcpResponse(BaseModel): - field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None +class McpError(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + code: StrictInt """ - The _meta property is reserved by ACP to allow clients and agents to attach additional - metadata to their interactions. Implementations MUST NOT make assumptions about values at - these keys. - - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + Inner MCP error code; never an ACP error code. + """ + message: str + """ + Inner MCP error message. + """ + data: Optional[Any] = None + """ + Optional error data; explicit null is retained. """ @@ -2572,6 +2623,35 @@ class AcceptNesNotification(BaseModel): """ +class MessageMcpNotification(BaseModel): + server_id: Annotated[str, Field(alias="serverId")] + """ + The declared ACP MCP server handling the associated request. + """ + request_id: Annotated[str, Field(alias="requestId")] + """ + The identifier of the active inner MCP request. + """ + 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/extensibility) + """ + + class CancelRequestNotification(BaseModel): request_id: Annotated[Optional[Union[int, str]], Field(alias="requestId")] """ @@ -3069,25 +3149,14 @@ def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHand return skip_invalid_items(v, handler, info) -class ConnectMcpRequest(BaseModel): +class MessageMcpRequest(BaseModel): server_id: Annotated[str, Field(alias="serverId")] """ - The ACP MCP server ID that was provided by the component declaring the MCP server. + The declared ACP MCP server receiving this request. """ - field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + request_id: Annotated[str, Field(alias="requestId")] """ - The _meta property is reserved by ACP to allow clients and agents to attach additional - metadata to their interactions. Implementations MUST NOT make assumptions about values at - these keys. - - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - """ - - -class MessageMcpRequest(BaseModel): - connection_id: Annotated[str, Field(alias="connectionId")] - """ - The MCP-over-ACP connection this message is sent on. + The caller-generated identifier for the inner MCP request. """ method: str """ @@ -3623,6 +3692,96 @@ class AvailableCommandInput(RootModel[UnstructuredCommandInput]): """ +class SubagentSessionCapabilities(BaseModel): + cancel: Optional[SessionCancelCapabilities] = None + """ + Permits the client to cancel this child's current work without ending + the session. Omitted or `null` means unsupported; an object (including + `{}`) means supported. + """ + 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. + """ + + @field_validator("cancel", 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 StateUpdate1(RunningStateUpdate): + state: Literal["running"] = "running" + + +class StateUpdate2(IdleStateUpdate): + state: Literal["idle"] = "idle" + + +class StateUpdate3(RequiresActionStateUpdate): + state: Literal["requires_action"] = "requires_action" + + +class StateUpdate4(UnknownStateUpdate): + state: Literal["unknown"] = "unknown" + + +class SubagentUpdate(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The opaque session ID identifying the child in all ACP messages. + """ + title: Optional[str] = None + """ + The parent's human-readable display title for this child. It need not be unique. + + Omitted means unchanged; `null` clears it. If unset, the Client chooses + a fallback presentation. + """ + description: Optional[str] = None + """ + The parent's human-readable description of the child's role or purpose. + + Omitted means unchanged; `null` clears it. If unset, the Client chooses + a fallback presentation. This is current display metadata, not the + history of instructions sent to the child. + """ + capabilities: Optional[SubagentSessionCapabilities] = None + """ + Client-initiated session mutations permitted for this subagent session. + + Omitted means unchanged; `null` clears the capability set and disables + child mutations. If never supplied, no session mutations are permitted. + Read-only operations retain their normal protocol semantics and capability + requirements. A concrete object replaces the whole capability set. + """ + state: Optional[Union[StateUpdate1, StateUpdate2, StateUpdate3, StateUpdate4, StateUpdate5]] = None + """ + Current state snapshot for the child session. + + Omitted means unchanged; `null` clears the current activity without + asserting idle or sending an `unknown` snapshot. A concrete state + replaces the previous state object wholesale. If never supplied, the + current activity is unset/unconfirmed. + """ + 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/extensibility) + Omitted means unchanged; `null` removes the metadata. + """ + + @field_validator("capabilities", "description", "state", "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 SessionConfigOptionsCapabilities(BaseModel): boolean: Optional[BooleanConfigOptionCapabilities] = None """ @@ -3999,6 +4158,17 @@ class AcceptElicitationResponse(ElicitationAcceptAction): action: Literal["accept"] = "accept" +class McpErrorResponse(BaseModel): + error: McpError + """ + Required, non-null MCP error object. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + Optional ACP carrier metadata. + """ + + class TextDocumentContentChangeEvent(BaseModel): range: Optional[Range] = None """ @@ -4249,6 +4419,10 @@ class AgentPlanUpdate(Plan): session_update: Annotated[Literal["plan"], Field(alias="sessionUpdate")] = "plan" +class SessionUpdateSubagentUpdate(SubagentUpdate): + session_update: Annotated[Literal["subagent_update"], Field(alias="sessionUpdate")] = "subagent_update" + + class ContentChunk(BaseModel): content: Annotated[ Union[ @@ -4409,6 +4583,90 @@ class CompactionSummaryChunk(BaseModel): """ +class SessionMessage(BaseModel): + message_id: Annotated[str, Field(alias="messageId")] + """ + Identifier of this message within the enclosing session's transcript. + """ + sender_session_id: Annotated[Optional[str], Field(alias="senderSessionId")] = None + """ + Optional sending session identity; omission or `null` retains a known value. + """ + recipient_session_id: Annotated[Optional[str], Field(alias="recipientSessionId")] = None + """ + Optional receiving session identity; omission or `null` retains a known value. + """ + content: Optional[ + List[ + Annotated[ + Union[ + TextContentBlock, + ImageContentBlock, + AudioContentBlock, + ResourceContentBlock, + EmbeddedResourceContentBlock, + ], + Field(discriminator="type"), + ] + ] + ] = None + """ + Omitted leaves content unchanged; `null` or `[]` clears it. + A non-empty array replaces all content. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + Omitted leaves metadata unchanged; `null` removes it. + + Implementations MUST NOT make assumptions about values in `_meta`. + """ + + @field_validator("recipient_session_id", "sender_session_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) + + @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 SessionMessageChunk(BaseModel): + message_id: Annotated[str, Field(alias="messageId")] + """ + Identifier of this message within the enclosing session's transcript. + """ + sender_session_id: Annotated[Optional[str], Field(alias="senderSessionId")] = None + """ + Optional sending session identity; omission or `null` retains a known value. + """ + recipient_session_id: Annotated[Optional[str], Field(alias="recipientSessionId")] = None + """ + Optional receiving session identity; omission or `null` retains a known value. + """ + content: Annotated[ + Union[ + TextContentBlock, ImageContentBlock, AudioContentBlock, ResourceContentBlock, EmbeddedResourceContentBlock + ], + Field(discriminator="type"), + ] + """ + A single content block appended to the message. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + Optional and nullable chunk-scoped metadata; omitted or `null` means none. + + Implementations MUST NOT make assumptions about values in `_meta`. + """ + + @field_validator("recipient_session_id", "sender_session_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 ClientSessionCapabilities(BaseModel): compaction: Optional[CompactionCapabilities] = None """ @@ -4920,6 +5178,14 @@ class SessionUpdateCompactionSummaryChunk(CompactionSummaryChunk): ) +class SessionUpdateSessionMessage(SessionMessage): + session_update: Annotated[Literal["session_message"], Field(alias="sessionUpdate")] = "session_message" + + +class SessionUpdateSessionMessageChunk(SessionMessageChunk): + session_update: Annotated[Literal["session_message_chunk"], Field(alias="sessionUpdate")] = "session_message_chunk" + + class ToolCall(BaseModel): tool_call_id: Annotated[str, Field(alias="toolCallId")] """ @@ -5029,6 +5295,19 @@ class ClientCapabilities(BaseModel): Optional. Omitted or `null` both mean the client does not advertise any session-related extensions. """ + subagents: Optional[SubagentCapabilities] = None + """ + **UNSTABLE** + + This capability is not part of the spec yet, and may be removed or changed at any point. + + Whether the client understands exposed subagent sessions. + + Optional and nullable. Omitted or `null` both mean the client does not + advertise support. + Supplying `{}` means the client understands child associations, work-state + snapshots, session-directed messages, and restricted-session semantics. + """ plan: Optional[PlanCapabilities] = None """ **UNSTABLE** @@ -5084,7 +5363,7 @@ class ClientCapabilities(BaseModel): See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) """ - @field_validator("auth", "elicitation", "fs", "nes", "plan", "session", "terminal", mode="wrap") + @field_validator("auth", "elicitation", "fs", "nes", "plan", "session", "subagents", "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) @@ -5148,12 +5427,10 @@ class ClientResponseMessage(BaseModel): ReleaseTerminalResponse, WaitForTerminalExitResponse, KillTerminalResponse, - ConnectMcpResponse, - DisconnectMcpResponse, - AcceptElicitationResponse, - DeclineElicitationResponse, - CancelElicitationResponse, - OtherElicitationResponse, + Union[ + AcceptElicitationResponse, DeclineElicitationResponse, CancelElicitationResponse, OtherElicitationResponse + ], + Union[McpResultResponse, McpErrorResponse], Any, ] """ @@ -5426,7 +5703,11 @@ class InitializeRequest(BaseModel): """ client_capabilities: Annotated[ Optional[ClientCapabilities], Field(alias="clientCapabilities", validate_default=True) - ] = {"fs": {"readTextFile": False, "writeTextFile": False}, "terminal": False, "auth": {"terminal": False}} + ] = { + "fs": {"readTextFile": False, "writeTextFile": False}, + "terminal": False, + "auth": {"terminal": False}, + } """ Capabilities supported by the client. """ @@ -5486,7 +5767,11 @@ class AgentCapabilities(BaseModel): """ prompt_capabilities: Annotated[ Optional[PromptCapabilities], Field(alias="promptCapabilities", validate_default=True) - ] = {"image": False, "audio": False, "embeddedContext": False} + ] = { + "image": False, + "audio": False, + "embeddedContext": False, + } """ Prompt capabilities supported by the agent. """ @@ -5586,6 +5871,9 @@ class SessionNotification(BaseModel): SessionUpdateNotice, SessionUpdateCompactionUpdate, SessionUpdateCompactionSummaryChunk, + SessionUpdateSubagentUpdate, + SessionUpdateSessionMessage, + SessionUpdateSessionMessageChunk, ], Field(discriminator="session_update"), ] @@ -5631,9 +5919,7 @@ class ClientRequest(BaseModel): StartNesRequest, SuggestNesRequest, CloseNesRequest, - MessageMcpRequest, - SetSessionConfigOptionBooleanRequest, - SetSessionConfigOptionSelectRequest, + Union[SetSessionConfigOptionBooleanRequest, SetSessionConfigOptionSelectRequest], Any, ] ] = None @@ -5661,15 +5947,12 @@ class AgentRequest(BaseModel): ReleaseTerminalRequest, WaitForTerminalExitRequest, KillTerminalRequest, - ConnectMcpRequest, MessageMcpRequest, - DisconnectMcpRequest, - CreateOtherSessionElicitationRequest, - CreateOtherRequestElicitationRequest, - CreateFormSessionElicitationRequest, - CreateFormRequestElicitationRequest, - CreateUrlSessionElicitationRequest, - CreateUrlRequestElicitationRequest, + Union[ + Union[CreateOtherSessionElicitationRequest, CreateOtherRequestElicitationRequest], + Union[CreateFormSessionElicitationRequest, CreateFormRequestElicitationRequest], + Union[CreateUrlSessionElicitationRequest, CreateUrlRequestElicitationRequest], + ], Any, ] ] = None @@ -5735,7 +6018,7 @@ class AgentNotification(BaseModel): """ The notification method name. """ - params: Optional[Union[SessionNotification, CompleteElicitationNotification, MessageMcpNotification, Any]] = None + params: Optional[Union[SessionNotification, CompleteElicitationNotification, Any]] = None """ Method-specific notification parameters. """ @@ -5780,6 +6063,8 @@ class AgentResponse(RootModel[Union[AgentResponseMessage, AgentErrorMessage]]): """ +MessageMcpResponse = Annotated[Union[McpResultResponse, McpErrorResponse], Field(union_mode="left_to_right")] + PermissionOptionKind = Literal["allow_once", "allow_always", "reject_once", "reject_always"] PlanEntryPriority = Literal["high", "medium", "low"] PlanEntryStatus = Literal["pending", "in_progress", "completed"] diff --git a/tests/conftest.py b/tests/conftest.py index 38c501f3..61933534 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -10,10 +10,8 @@ AcceptElicitationResponse, AuthenticateResponse, CompleteElicitationNotification, - ConnectMcpResponse, CreateElicitationResponse, CreateTerminalResponse, - DisconnectMcpResponse, ElicitationMode, InitializeResponse, KillTerminalResponse, @@ -237,22 +235,11 @@ async def complete_elicitation(self, elicitation_id: str, **kwargs: Any) -> None CompleteElicitationNotification(elicitation_id=elicitation_id, field_meta=kwargs or None) ) - async def connect_mcp(self, server_id: str, **kwargs: Any) -> ConnectMcpResponse: - raise RequestError.method_not_found("mcp/connect") - - async def disconnect_mcp(self, connection_id: str, **kwargs: Any) -> DisconnectMcpResponse: - raise RequestError.method_not_found("mcp/disconnect") - async def mcp_message( - self, connection_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any + self, server_id: str, request_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any ) -> Any: raise RequestError.method_not_found("mcp/message") - async def notify_mcp( - self, connection_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any - ) -> None: - raise RequestError.method_not_found("mcp/message") - async def ext_method(self, method: str, params: dict) -> dict: self.ext_calls.append((method, params)) if method == "example.com/ping": diff --git a/tests/test_protocol_method_coverage.py b/tests/test_protocol_method_coverage.py index 3c5b8216..8e059975 100644 --- a/tests/test_protocol_method_coverage.py +++ b/tests/test_protocol_method_coverage.py @@ -113,39 +113,32 @@ async def handler(**kwargs): @pytest.mark.asyncio -async def test_mcp_connection_lifecycle(connect, client): - client.connect_mcp = AsyncMock(return_value=schema.ConnectMcpResponse(connection_id="c")) - client.disconnect_mcp = AsyncMock(return_value=None) - connection, _ = connect(use_unstable_protocol=True) - assert (await connection.connect_mcp(server_id="m", trace="test")).connection_id == "c" - client.connect_mcp.assert_awaited_once_with(server_id="m", trace="test") - assert await connection.disconnect_mcp(connection_id="c") == schema.DisconnectMcpResponse() - client.disconnect_mcp.assert_awaited_once_with(connection_id="c") - - -@pytest.mark.asyncio -@pytest.mark.parametrize("response", [None, {}, {"tools": []}, [1, "x"], False, 42]) -@pytest.mark.parametrize("direction", ["agent", "client"]) -async def test_mcp_requests_and_notifications_share_method(connect, agent, client, direction, response): - receiver = agent if direction == "agent" else client - receiver.mcp_message = AsyncMock(return_value=response) +@pytest.mark.parametrize("result", [None, {}, {"tools": []}, [1, "x"], False, 42]) +async def test_mcp_requests_and_notifications_share_method(connect, agent, client, result): received = asyncio.Event() async def notify_mcp(**kwargs): - assert kwargs == {"connection_id": "c", "method": "notifications/initialized", "params": None, "trace": "test"} + assert kwargs == { + "server_id": "s", + "request_id": "r", + "method": "notifications/progress", + "params": None, + "trace": "test", + } received.set() - receiver.notify_mcp = notify_mcp + agent.notify_mcp = notify_mcp + client.mcp_message = AsyncMock(return_value=schema.McpResultResponse(result=result)) agent_side, client_side = connect(use_unstable_protocol=True) - sender = client_side if direction == "agent" else agent_side - assert ( - await sender.mcp_message(connection_id="c", method="tools/list", params={"cursor": "next"}, trace="test") - == response + response = await agent_side.mcp_message( + server_id="s", request_id="r", method="tools/list", params={"cursor": "next"}, trace="test" ) - receiver.mcp_message.assert_awaited_once_with( - connection_id="c", method="tools/list", params={"cursor": "next"}, trace="test" + assert isinstance(response, schema.McpResultResponse) + assert response.result == result + client.mcp_message.assert_awaited_once_with( + server_id="s", request_id="r", method="tools/list", params={"cursor": "next"}, trace="test" ) - await sender.notify_mcp(connection_id="c", method="notifications/initialized", trace="test") + await client_side.notify_mcp(server_id="s", request_id="r", method="notifications/progress", trace="test") await asyncio.wait_for(received.wait(), 2) diff --git a/tests/test_stateless_mcp.py b/tests/test_stateless_mcp.py new file mode 100644 index 00000000..4c7e6068 --- /dev/null +++ b/tests/test_stateless_mcp.py @@ -0,0 +1,247 @@ +"""Stateless MCP wire contracts and loopback behavior for both ACP versions.""" + +import asyncio +from typing import Any, cast + +import pytest +import pytest_asyncio +from pydantic import TypeAdapter, ValidationError + +from acp import schema as v1_schema +from acp._transport import memory_transport_pair +from acp.agent.connection import AgentSideConnection +from acp.client.connection import ClientSideConnection +from acp.exceptions import RequestError +from acp.experimental import v2 +from acp.interfaces import Agent as AgentProtocol +from acp.interfaces import Client as ClientProtocol + + +@pytest.fixture(params=[v1_schema, v2.schema], ids=["v1", "v2"]) +def schema(request): + return request.param + + +@pytest.mark.parametrize( + "result", [None, False, 0, "text", [None], {"resultType": "input_required", "requestState": {"opaque": None}}] +) +def test_result_carrier_preserves_opaque_json_and_prefers_result(schema, result): + carrier = TypeAdapter(schema.MessageMcpResponse).validate_python({ + "result": result, + "error": {"code": -32000, "message": "ignored"}, + "unknown": True, + "_meta": "invalid", + }) + assert isinstance(carrier, schema.McpResultResponse) + assert carrier.model_dump(mode="json", by_alias=True, exclude_none=True, exclude_unset=True) == {"result": result} + + +@pytest.mark.parametrize("data", [{}, {"data": None}, {"data": {"nested": None}}]) +def test_mcp_error_preserves_data_presence_and_extensions(schema, data): + error = {"code": -32000, "message": "MCP error, not ACP auth", "vendor": {"extra": None}, "nullable": None, **data} + carrier = TypeAdapter(schema.MessageMcpResponse).validate_python({"error": error, "_meta": {"trace": "outer"}}) + assert isinstance(carrier, schema.McpErrorResponse) + assert carrier.model_dump(mode="json", by_alias=True, exclude_none=True, exclude_unset=True) == { + "error": error, + "_meta": {"trace": "outer"}, + } + + +@pytest.mark.parametrize( + "value", + [ + None, + {}, + {"error": None}, + {"error": {}}, + {"error": {"code": True, "message": "bad"}}, + {"error": {"code": "1", "message": "bad"}}, + ], +) +def test_invalid_carriers_are_rejected(schema, value): + with pytest.raises(ValidationError): + TypeAdapter(schema.MessageMcpResponse).validate_python(value) + + +@pytest.mark.parametrize("model_name", ["MessageMcpRequest", "MessageMcpNotification"]) +@pytest.mark.parametrize( + "invalid", + [ + {"connectionId": "old", "method": "ping"}, + {"serverId": "s", "method": "ping"}, + {"serverId": "s", "requestId": 1, "method": "ping"}, + {"serverId": "s", "requestId": "r", "method": "ping", "params": []}, + ], +) +def test_envelope_requires_server_and_logical_request_ids(schema, model_name, invalid): + with pytest.raises(ValidationError): + getattr(schema, model_name).model_validate(invalid) + + +@pytest_asyncio.fixture +async def peers(schema): + class Agent: + def __init__(self): + self.notifications = asyncio.Queue() + + async def initialize(self, **kwargs): + if schema is v2.schema: + return schema.InitializeResponse( + protocol_version=2, info=schema.Implementation(name="test", version="1") + ) + return schema.InitializeResponse(protocol_version=1) + + async def notify_mcp(self, **kwargs): + await self.notifications.put(kwargs) + + class Client: + def __init__(self): + self.outcome: Any = {"result": None} + self.calls = [] + + async def mcp_message(self, **kwargs): + self.calls.append(kwargs) + if isinstance(self.outcome, Exception): + raise self.outcome + if callable(self.outcome): + return await self.outcome(**kwargs) + return self.outcome + + agent, client = Agent(), Client() + a_transport, c_transport = memory_transport_pair() + if schema is v2.schema: + a = v2.AgentSideConnection(cast(AgentProtocol, agent), a_transport) + c = v2.ClientSideConnection(cast(ClientProtocol, client), c_transport) + await c.initialize(protocol_version=2, info=schema.Implementation(name="test", version="1")) + else: + a = AgentSideConnection(cast(AgentProtocol, agent), a_transport, use_unstable_protocol=True) + c = ClientSideConnection(cast(ClientProtocol, client), c_transport, use_unstable_protocol=True) + try: + yield a, c, agent, client + finally: + await c.close() + await a.close() + + +@pytest.mark.asyncio +async def test_request_metadata_notifications_and_error_domains(peers, schema): + a, c, agent, client = peers + inner = { + "_meta": { + "io.modelcontextprotocol/protocolVersion": "2026-07-28", + "io.modelcontextprotocol/clientCapabilities": {}, + "progressToken": "p", + } + } + + async def handle(**kwargs): + await c.notify_mcp( + server_id=kwargs["server_id"], + request_id=kwargs["request_id"], + method="notifications/progress", + params={"progressToken": "p", "progress": 1}, + trace="notification", + ) + return {"error": {"code": -32000, "message": "inner", "data": None, "vendor": 1}} + + client.outcome = handle + response = await a.mcp_message( + server_id="s", request_id="logical", method="tools/call", params=inner, trace="outer" + ) + assert isinstance(response, schema.McpErrorResponse) + assert response.error.code == -32000 + assert response.error.model_dump(exclude_unset=True) == { + "code": -32000, + "message": "inner", + "data": None, + "vendor": 1, + } + assert client.calls == [ + {"server_id": "s", "request_id": "logical", "method": "tools/call", "params": inner, "trace": "outer"} + ] + notification = await asyncio.wait_for(agent.notifications.get(), 1) + assert notification == { + "server_id": "s", + "request_id": "logical", + "method": "notifications/progress", + "params": {"progressToken": "p", "progress": 1}, + "trace": "notification", + } + client.outcome = RequestError(-33001, "server unavailable") + with pytest.raises(RequestError) as error: + await a.mcp_message(server_id="s", request_id="next", method="tools/list") + assert isinstance(error.value, RequestError) + assert error.value.code == -33001 + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + "outcome", [{"result": None}, {"result": {"resultType": "input_required", "requestState": {"opaque": None}}}] +) +async def test_loopback_preserves_null_and_mrtr_result(peers, outcome): + a, _, _, client = peers + client.outcome = outcome + response = await a.mcp_message(server_id="s", request_id="r", method="tools/call") + assert response.result == outcome["result"] + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + "outcome", [None, {}, {"result": None, "error": {"code": 1, "message": "both"}}, {"error": None}] +) +async def test_invalid_outgoing_outcomes_are_binding_failures(peers, outcome): + a, _, _, client = peers + client.outcome = outcome + with pytest.raises(RequestError) as error: + await a.mcp_message(server_id="s", request_id="r", method="tools/call") + assert isinstance(error.value, RequestError) + assert error.value.code == -33002 + + +@pytest.mark.asyncio +async def test_cancellation_is_per_outer_request(peers): + a, _, _, client = peers + started, cleaned = asyncio.Event(), asyncio.Event() + + async def handle(request_id, **kwargs): + if request_id == "sibling": + return {"result": None} + started.set() + try: + await asyncio.Event().wait() + finally: + cleaned.set() + + client.outcome = handle + pending = asyncio.create_task(a.mcp_message(server_id="s", request_id="long", method="subscriptions/listen")) + await asyncio.wait_for(started.wait(), 1) + assert (await a.mcp_message(server_id="s", request_id="sibling", method="tools/list")).result is None + pending.cancel() + with pytest.raises(asyncio.CancelledError): + await pending + await asyncio.wait_for(cleaned.wait(), 1) + + +@pytest.mark.asyncio +async def test_removed_binding_methods_and_reverse_calls_are_not_exposed(peers): + a, c, _, _ = peers + assert not hasattr(a, "connect_mcp") + assert not hasattr(a, "disconnect_mcp") + assert not hasattr(a, "notify_mcp") + assert not hasattr(c, "mcp_message") + for method in ("mcp/connect", "mcp/disconnect"): + with pytest.raises(RequestError) as error: + await a._conn.send_request(method, {"serverId": "s"}) + assert isinstance(error.value, RequestError) + assert error.value.code == -32601 + + +@pytest.mark.asyncio +@pytest.mark.parametrize("data", [{}, {"data": None}]) +@pytest.mark.parametrize("extensions", [{}, {"vendor": None}]) +async def test_loopback_preserves_error_data_presence(peers, data, extensions): + a, _, _, client = peers + error = {"code": -32602, "message": "inner", **data, **extensions} + client.outcome = {"error": error} + response = await a.mcp_message(server_id="s", request_id="r", method="tools/call") + assert response.error.model_dump(exclude_unset=True) == error diff --git a/tests/test_v2_routing.py b/tests/test_v2_routing.py index 976d0731..af04de61 100644 --- a/tests/test_v2_routing.py +++ b/tests/test_v2_routing.py @@ -24,8 +24,8 @@ def test_protocols_cover_wire_methods_and_match_connection_signatures(protocol, assert inspect.signature(getattr(protocol, spec.handler)) == inspect.signature( getattr(connection, spec.handler) ) - assert "mcp/message" in {spec.method for spec in requests} - assert "mcp/message" in {spec.method for spec in notifications} + assert ("mcp/message" in {spec.method for spec in requests}) == (protocol is v2.Client) + assert ("mcp/message" in {spec.method for spec in notifications}) == (protocol is v2.Agent) @pytest.mark.asyncio @@ -37,6 +37,7 @@ class Agent(v2.Agent): with pytest.raises(RequestError) as error: await router("session/new", {"cwd": "/workspace"}, False) assert isinstance(error.value, RequestError) + assert isinstance(error.value, RequestError) assert error.value.code == -32601 assert await router("session/cancel", {"sessionId": "s"}, True) is None @@ -66,7 +67,10 @@ async def mcp_message(self, **kwargs: Any) -> Any: await router("session/prompt", {"sessionId": "s", "prompt": []}, False) assert agent.calls == 1 assert isinstance(await router("auth/logout", {}, False), v2.schema.LogoutAuthResponse) - assert await router("mcp/message", {"connectionId": "m", "method": "ping"}, False) is None + with pytest.raises(RequestError) as error: + await router("mcp/message", {"serverId": "s", "requestId": "r", "method": "ping"}, False) + assert isinstance(error.value, RequestError) + assert error.value.code == -32601 @pytest.mark.asyncio diff --git a/tests/test_v2_runtime.py b/tests/test_v2_runtime.py index d93da0b8..6f623367 100644 --- a/tests/test_v2_runtime.py +++ b/tests/test_v2_runtime.py @@ -144,8 +144,10 @@ async def cancel_session(self, session_id: str, **kwargs: Any) -> None: notification = v2.schema.CancelSessionNotification(session_id=session_id, **kwargs) await self.notifications.put(("cancel", notification)) - async def notify_mcp(self, connection_id: str, method: str, **kwargs: Any) -> None: - notification = v2.schema.MessageMcpNotification(connection_id=connection_id, method=method, **kwargs) + async def notify_mcp(self, server_id: str, request_id: str, method: str, **kwargs: Any) -> None: + notification = v2.schema.MessageMcpNotification( + server_id=server_id, request_id=request_id, method=method, **kwargs + ) await self.notifications.put(("mcp", notification)) @@ -403,12 +405,12 @@ async def test_extension_and_notification_names_are_explicit() -> None: await client_connection.send_extension_request("vendor/do") await client_connection.cancel_session(session_id="session-1") - await client_connection.notify_mcp(connection_id="mcp-1", method="notifications/progress") + await client_connection.notify_mcp(server_id="mcp-1", request_id="r", method="notifications/progress") cancel_kind, cancel = await asyncio.wait_for(agent.notifications.get(), timeout=1) mcp_kind, mcp = await asyncio.wait_for(agent.notifications.get(), timeout=1) assert (cancel_kind, cancel.session_id) == ("cancel", "session-1") - assert (mcp_kind, mcp.connection_id) == ("mcp", "mcp-1") + assert (mcp_kind, mcp.server_id) == ("mcp", "mcp-1") finally: await client_connection.close() await agent_connection.close() From 66bc0071a03daf8e9f0901942ca579aabc3b03a8 Mon Sep 17 00:00:00 2001 From: Raymond Feng Date: Wed, 18 Nov 2026 10:45:12 -0800 Subject: [PATCH 2/2] feat(schema)!: bump ACP v1 schema to 1.33.0 Regenerate the v1 bindings from schema-v1.33.0 (`make gen-all`). Builds on the stateless MCP-over-ACP binding, which 1.33 requires. - Pass the new session fields to the wire. The signature generator added them to the senders, but the hand-written bodies dropped them: `system_prompt` and `config_options` on new/load/resume/fork, `cursor_id` on fork, `archived` on list. Add a wire test, and a test that every sender uses all its parameters. - Add the methods 1.33 introduces, all unstable: `archive_session`, `unarchive_session`, `session_status`, `session_options`, `set_session_title`, `auth_status`, and the client notification `auth_status_update`. - Remove next edit suggestions and the document notifications, which the schema removed (agent-client-protocol db2116ef, #2266). - Name the 1.33 `PlanUpdateContent` variants by kind. The schema dropped the `file` variant, and the positional name map turned `markdown` into `PlanUpdateFile`. Drop the stale `NesSuggestion` map. - Move two tests off models the schema changed: `ToolCallLocation.line` for the default-on-error salvage, `StringPropertySchema.format` for inline literals. - Regenerate experimental v2 at its current pin (alpha.7) with the current generator. BREAKING CHANGE: the NES and document methods are gone (`start_nes`, `suggest_nes`, `close_nes`, `accept_nes`, `reject_nes`, `did_open`, `did_change`, `did_close`, `did_save`, `did_focus`), and so are their models. `PlanUpdateFile` is gone with the schema's `file` plan update. Co-Authored-By: Claude Opus 5.5 --- docs/quickstart.md | 7 +- schema/VERSION | 2 +- schema/meta.json | 23 +- schema/schema.json | 5948 ++++++++++++------------ scripts/gen_schema_v1.py | 13 +- src/acp/__init__.py | 26 - src/acp/agent/connection.py | 32 +- src/acp/client/connection.py | 280 +- src/acp/experimental/v2/schema.py | 41 +- src/acp/interfaces.py | 159 +- src/acp/meta.py | 19 +- src/acp/schema.py | 3870 ++++++++------- tests/conftest.py | 4 + tests/test_deserialize.py | 7 +- tests/test_gen_all.py | 21 +- tests/test_protocol_method_coverage.py | 89 +- tests/test_sender_parameters.py | 23 + tests/test_session_request_fields.py | 39 + 18 files changed, 5530 insertions(+), 5073 deletions(-) create mode 100644 tests/test_sender_parameters.py create mode 100644 tests/test_session_request_fields.py diff --git a/docs/quickstart.md b/docs/quickstart.md index 00d619ca..0abbfd11 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -200,11 +200,12 @@ Check the peer's advertised capabilities before calling these methods. | `session/delete` | `delete_session(session_id=...)` | Agent | | `providers/list`, `providers/set`, `providers/disable` | `list_providers`, `set_provider`, `disable_provider` | Agent | | `logout` | `logout()` | Agent | +| `session/archive`, `session/unarchive` | `archive_session`, `unarchive_session` | Agent | +| `session/status`, `session/options`, `session/set_title` | `session_status`, `session_options`, `set_session_title` | Agent | +| `auth/status` | `auth_status()` | Agent | +| `auth/status_update` (notification) | `auth_status_update` | Client | | `mcp/message` (request) | `mcp_message` | Client/provider | | `mcp/message` (notification) | `notify_mcp` | Agent | -| `nes/start`, `nes/suggest`, `nes/close` | `start_nes`, `suggest_nes`, `close_nes` | Agent | -| `nes/accept`, `nes/reject` | `accept_nes`, `reject_nes` | Agent | -| `document/didOpen`, `document/didChange`, `document/didClose`, `document/didSave`, `document/didFocus` | `did_open`, `did_change`, `did_close`, `did_save`, `did_focus` | Agent | For example, an agent that advertises session deletion implements: diff --git a/schema/VERSION b/schema/VERSION index ee41110d..1c14e912 100644 --- a/schema/VERSION +++ b/schema/VERSION @@ -1 +1 @@ -refs/tags/schema-v1.24.1 +refs/tags/schema-v1.33.0 diff --git a/schema/meta.json b/schema/meta.json index 956449fc..2736f7fc 100644 --- a/schema/meta.json +++ b/schema/meta.json @@ -16,19 +16,15 @@ "session_list": "session/list", "session_delete": "session/delete", "session_fork": "session/fork", + "session_archive": "session/archive", + "session_unarchive": "session/unarchive", + "session_status": "session/status", + "session_options": "session/options", + "session_set_title": "session/set_title", "session_resume": "session/resume", "session_close": "session/close", "logout": "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" + "auth_status": "auth/status" }, "clientMethods": { "session_request_permission": "session/request_permission", @@ -42,9 +38,14 @@ "terminal_kill": "terminal/kill", "mcp_message": "mcp/message", "elicitation_create": "elicitation/create", - "elicitation_complete": "elicitation/complete" + "elicitation_complete": "elicitation/complete", + "auth_status_update": "auth/status_update" }, "protocolMethods": { "cancel_request": "$/cancel_request" + }, + "proxyMethods": { + "proxy_initialize": "proxy/initialize", + "proxy_successor": "proxy/successor" } } diff --git a/schema/schema.json b/schema/schema.json index 4938b2ff..0322826d 100644 --- a/schema/schema.json +++ b/schema/schema.json @@ -109,7 +109,7 @@ "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/cancellation)", + "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/v1/draft/cancellation)", "allOf": [ { "$ref": "#/$defs/CancelRequestNotification" @@ -129,6 +129,48 @@ "method" ], "x-docs-ignore": true + }, + { + "title": "Proxy", + "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/ProxyRequest" + } + ] + }, + { + "title": "Response", + "allOf": [ + { + "$ref": "#/$defs/ProxyResponse" + } + ] + }, + { + "title": "Notification", + "allOf": [ + { + "$ref": "#/$defs/ProxyNotification" + } + ] + } + ] } ], "$defs": { @@ -156,7 +198,7 @@ "anyOf": [ { "title": "WriteTextFileRequest", - "description": "Writes content to a text file in the client's file system.\n\nOnly available if the client advertises the `fs.writeTextFile` capability.\nAllows the agent to create or modify files within the client's environment.\n\nSee protocol docs: [Client](https://agentclientprotocol.com/protocol/overview#client)", + "description": "Writes content to a text file in the client's file system.\n\nOnly available if the client advertises the `fs.writeTextFile` capability.\nAllows the agent to create or modify files within the client's environment.\n\nSee protocol docs: [Client](https://agentclientprotocol.com/protocol/v1/draft/overview#client)", "allOf": [ { "$ref": "#/$defs/WriteTextFileRequest" @@ -165,7 +207,7 @@ }, { "title": "ReadTextFileRequest", - "description": "Reads content from a text file in the client's file system.\n\nOnly available if the client advertises the `fs.readTextFile` capability.\nAllows the agent to access file contents within the client's environment.\n\nSee protocol docs: [Client](https://agentclientprotocol.com/protocol/overview#client)", + "description": "Reads content from a text file in the client's file system.\n\nOnly available if the client advertises the `fs.readTextFile` capability.\nAllows the agent to access file contents within the client's environment.\n\nSee protocol docs: [Client](https://agentclientprotocol.com/protocol/v1/draft/overview#client)", "allOf": [ { "$ref": "#/$defs/ReadTextFileRequest" @@ -174,7 +216,7 @@ }, { "title": "RequestPermissionRequest", - "description": "Requests permission from the user for a tool call 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 the prompt turn via `session/cancel`, it MUST\nrespond to this request with `RequestPermissionOutcome::Cancelled`.\n\nSee protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/tool-calls#requesting-permission)", + "description": "Requests permission from the user for a tool call 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 the prompt turn via `session/cancel`, it MUST\nrespond to this request with the `cancelled` outcome.\n\nSee protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/v1/draft/tool-calls#requesting-permission)", "allOf": [ { "$ref": "#/$defs/RequestPermissionRequest" @@ -183,7 +225,7 @@ }, { "title": "CreateTerminalRequest", - "description": "Executes a command in a new terminal\n\nOnly available if the `terminal` Client capability is set to `true`.\n\nReturns a `TerminalId` that can be used with other terminal methods\nto get the current output, wait for exit, and kill the command.\n\nThe `TerminalId` can also be used to embed the terminal in a tool call\nby using the `ToolCallContent::Terminal` variant.\n\nThe Agent is responsible for releasing the terminal by using the `terminal/release`\nmethod.\n\nSee protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)", + "description": "Executes a command in a new terminal\n\nOnly available if the `terminal` Client capability is set to `true`.\n\nReturns a `TerminalId` that can be used with other terminal methods\nto get the current output, wait for exit, and kill the command.\n\nThe `TerminalId` can also be used to embed the terminal in a tool call\nby using `terminal` tool call content.\n\nThe Agent is responsible for releasing the terminal by using the `terminal/release`\nmethod.\n\nSee protocol docs: [Terminals](https://agentclientprotocol.com/protocol/v1/draft/terminals)", "allOf": [ { "$ref": "#/$defs/CreateTerminalRequest" @@ -192,7 +234,7 @@ }, { "title": "TerminalOutputRequest", - "description": "Gets the terminal output and exit status\n\nReturns the current content in the terminal without waiting for the command to exit.\nIf the command has already exited, the exit status is included.\n\nSee protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)", + "description": "Gets the terminal output and exit status\n\nReturns the current content in the terminal without waiting for the command to exit.\nIf the command has already exited, the exit status is included.\n\nSee protocol docs: [Terminals](https://agentclientprotocol.com/protocol/v1/draft/terminals)", "allOf": [ { "$ref": "#/$defs/TerminalOutputRequest" @@ -201,7 +243,7 @@ }, { "title": "ReleaseTerminalRequest", - "description": "Releases a terminal\n\nThe command is killed if it hasn't exited yet. Use `terminal/wait_for_exit`\nto wait for the command to exit before releasing the terminal.\n\nAfter release, the `TerminalId` can no longer be used with other `terminal/*` methods,\nbut tool calls that already contain it, continue to display its output.\n\nThe `terminal/kill` method can be used to terminate the command without releasing\nthe terminal, allowing the Agent to call `terminal/output` and other methods.\n\nSee protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)", + "description": "Releases a terminal\n\nThe command is killed if it hasn't exited yet. Use `terminal/wait_for_exit`\nto wait for the command to exit before releasing the terminal.\n\nAfter release, the `TerminalId` can no longer be used with other `terminal/*` methods,\nbut tool calls that already contain it, continue to display its output.\n\nThe `terminal/kill` method can be used to terminate the command without releasing\nthe terminal, allowing the Agent to call `terminal/output` and other methods.\n\nSee protocol docs: [Terminals](https://agentclientprotocol.com/protocol/v1/draft/terminals)", "allOf": [ { "$ref": "#/$defs/ReleaseTerminalRequest" @@ -210,7 +252,7 @@ }, { "title": "WaitForTerminalExitRequest", - "description": "Waits for the terminal command to exit and return its exit status\n\nSee protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)", + "description": "Waits for the terminal command to exit and return its exit status\n\nSee protocol docs: [Terminals](https://agentclientprotocol.com/protocol/v1/draft/terminals)", "allOf": [ { "$ref": "#/$defs/WaitForTerminalExitRequest" @@ -219,7 +261,7 @@ }, { "title": "KillTerminalRequest", - "description": "Kills the terminal command without releasing the terminal\n\nWhile `terminal/release` will also kill the command, this method will keep\nthe `TerminalId` valid so it can be used with other methods.\n\nThis method can be helpful when implementing command timeouts which terminate\nthe command as soon as elapsed, and then get the final output so it can be sent\nto the model.\n\nNote: Call `terminal/release` when `TerminalId` is no longer needed.\n\nSee protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)", + "description": "Kills the terminal command without releasing the terminal\n\nWhile `terminal/release` will also kill the command, this method will keep\nthe `TerminalId` valid so it can be used with other methods.\n\nThis method can be helpful when implementing command timeouts which terminate\nthe command as soon as elapsed, and then get the final output so it can be sent\nto the model.\n\nNote: Call `terminal/release` when `TerminalId` is no longer needed.\n\nSee protocol docs: [Terminals](https://agentclientprotocol.com/protocol/v1/draft/terminals)", "allOf": [ { "$ref": "#/$defs/KillTerminalRequest" @@ -228,7 +270,7 @@ }, { "title": "CreateElicitationRequest", - "description": "Requests structured user input via a form or URL.\n\nSee protocol docs: [Elicitation](https://agentclientprotocol.com/protocol/elicitation)", + "description": "Requests structured user input via a form or URL.\n\nSee protocol docs: [Elicitation](https://agentclientprotocol.com/protocol/v1/draft/elicitation)", "allOf": [ { "$ref": "#/$defs/CreateElicitationRequest" @@ -246,7 +288,7 @@ }, { "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/extensibility)", + "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/v1/draft/extensibility)", "allOf": [ { "$ref": "#/$defs/ExtRequest" @@ -309,7 +351,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -327,7 +369,7 @@ "x-method": "fs/write_text_file" }, "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/session-setup#session-id)", + "description": "A unique identifier for a conversation session between a client and agent.\n\nEach session has its own context, conversation history, and state, so one\nagent can run several independent sessions.\n\nSee protocol docs: [Session ID](https://agentclientprotocol.com/protocol/v1/draft/session-setup#session-id)", "type": "string" }, "ReadTextFileRequest": { @@ -353,8 +395,7 @@ "null" ], "format": "uint32", - "minimum": 0, - "x-deserialize-default-on-error": true + "minimum": 0 }, "limit": { "description": "Maximum number of lines to read.", @@ -363,11 +404,10 @@ "null" ], "format": "uint32", - "minimum": 0, - "x-deserialize-default-on-error": true + "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -384,7 +424,7 @@ "x-method": "fs/read_text_file" }, "RequestPermissionRequest": { - "description": "Request for user permission to execute a tool call.\n\nSent when the agent needs authorization before performing a sensitive operation.\n\nSee protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/tool-calls#requesting-permission)", + "description": "Request for user permission to execute a tool call.\n\nSent when the agent needs authorization before performing a sensitive operation.\n\nSee protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/v1/draft/tool-calls#requesting-permission)", "type": "object", "properties": { "sessionId": { @@ -411,7 +451,7 @@ } }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -429,7 +469,7 @@ "x-method": "session/request_permission" }, "ToolCallUpdate": { - "description": "An update to an existing tool call.\n\nUsed to report progress and results as tools execute. All fields except\nthe tool call ID are optional - only changed fields need to be included.\n\nSee protocol docs: [Updating](https://agentclientprotocol.com/protocol/tool-calls#updating)", + "description": "An update to an existing tool call.\n\nUsed to report progress and results as tools execute. All fields except\nthe tool call ID are optional - only changed fields need to be included.\n\nSee protocol docs: [Updating](https://agentclientprotocol.com/protocol/v1/draft/tool-calls#updating)", "type": "object", "properties": { "toolCallId": { @@ -513,7 +553,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -531,7 +571,7 @@ "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/tool-calls#creating)", + "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/v1/draft/tool-calls#creating)", "oneOf": [ { "description": "Reading files or data.", @@ -586,7 +626,7 @@ ] }, "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/tool-calls#status)", + "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/v1/draft/tool-calls#status)", "oneOf": [ { "description": "The tool call hasn't started running yet because the input is either\nstreaming or we're awaiting approval.", @@ -611,7 +651,7 @@ ] }, "ToolCallContent": { - "description": "Content produced by a tool call.\n\nTool calls can produce different types of content including\nstandard content blocks (text, images) or file diffs.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/tool-calls#content)", + "description": "Content produced by a tool call.\n\nTool calls can produce different types of content including\nstandard content blocks (text, images) or file diffs.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/v1/draft/tool-calls#content)", "oneOf": [ { "description": "Standard content block (text, images, resources).", @@ -650,7 +690,7 @@ ] }, { - "description": "Embed a terminal created with `terminal/create` by its id.\n\nThe terminal must be added before calling `terminal/release`.\n\nSee protocol docs: [Terminal](https://agentclientprotocol.com/protocol/terminals)", + "description": "Embed a terminal created with `terminal/create` by its id.\n\nThe terminal must be added before calling `terminal/release`.\n\nSee protocol docs: [Terminal](https://agentclientprotocol.com/protocol/v1/draft/terminals)", "type": "object", "properties": { "type": { @@ -666,6 +706,24 @@ "$ref": "#/$defs/Terminal" } ] + }, + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA display-only reference to another session, such as a subagent.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "session" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/SessionReference" + } + ] } ], "discriminator": { @@ -673,7 +731,7 @@ } }, "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 streamed through `session/update` notifications\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/content)", + "description": "Content blocks represent displayable information in the Agent Client Protocol.\n\nContent blocks appear in:\n- User prompts sent via `session/prompt`\n- Language model output streamed through `session/update` notifications\n- Progress updates and results from tool calls\n\nThis structure is compatible with the Model Context Protocol (MCP), so agents can\nforward content from MCP tool outputs without transformation.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/v1/draft/content)", "oneOf": [ { "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.", @@ -804,7 +862,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -850,7 +908,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -896,7 +954,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -935,7 +993,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -1007,7 +1065,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -1065,7 +1123,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -1100,7 +1158,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -1139,7 +1197,7 @@ ] }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -1165,7 +1223,7 @@ ] }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -1179,7 +1237,7 @@ ] }, "Diff": { - "description": "A diff representing file modifications.\n\nShows changes to files in a format suitable for display in the client UI.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/tool-calls#content)", + "description": "A diff representing file modifications.\n\nShows changes to files in a format suitable for display in the client UI.\n\nSee protocol docs: [Content](https://agentclientprotocol.com/protocol/v1/draft/tool-calls#content)", "type": "object", "properties": { "path": { @@ -1187,7 +1245,7 @@ "type": "string" }, "oldText": { - "description": "The original content (None for new files).", + "description": "The original content (omitted or `null` for new files).", "type": [ "string", "null" @@ -1199,7 +1257,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -1218,7 +1276,7 @@ "type": "string" }, "Terminal": { - "description": "Embed a terminal created with `terminal/create` by its id.\n\nThe terminal must be added before calling `terminal/release`.\n\nSee protocol docs: [Terminal](https://agentclientprotocol.com/protocol/terminals)", + "description": "Embed a terminal created with `terminal/create` by its id.\n\nThe terminal must be added before calling `terminal/release`.\n\nSee protocol docs: [Terminal](https://agentclientprotocol.com/protocol/v1/draft/terminals)", "type": "object", "properties": { "terminalId": { @@ -1230,7 +1288,7 @@ ] }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -1243,8 +1301,34 @@ "terminalId" ] }, + "SessionReference": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA display-only reference to another session that this tool call operates on,\nsuch as a subagent it created, delegated to, or is waiting on.\n\nThe referenced session must already be known to the Client through ordinary\nsession setup or a `subagent_update` announcement. The reference does not\nestablish ownership, grant any Client-initiated controls, or report that the\nreferenced session received or finished any work.", + "type": "object", + "properties": { + "sessionId": { + "description": "The referenced 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/v1/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId" + ] + }, "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/tool-calls#following-the-agent)", + "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/v1/draft/tool-calls#following-the-agent)", "type": "object", "properties": { "path": { @@ -1252,7 +1336,7 @@ "type": "string" }, "line": { - "description": "Optional line number within the file.", + "description": "Optional 1-based line number within the file.", "type": [ "integer", "null" @@ -1262,7 +1346,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -1300,7 +1384,7 @@ ] }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -1366,8 +1450,7 @@ "items": { "type": "string" }, - "x-deserialize-default-on-error": true, - "x-deserialize-skip-invalid-items": true + "x-deserialize-default-on-null": true }, "env": { "description": "Environment variables for the command.", @@ -1375,16 +1458,14 @@ "items": { "$ref": "#/$defs/EnvVariable" }, - "x-deserialize-default-on-error": true, - "x-deserialize-skip-invalid-items": true + "x-deserialize-default-on-null": true }, "cwd": { "description": "Working directory for the command. Must be an absolute path.", "type": [ "string", "null" - ], - "x-deserialize-default-on-error": true + ] }, "outputByteLimit": { "description": "Maximum number of output bytes to retain.\n\nWhen the limit is exceeded, the Client truncates from the beginning of the output\nto stay within the limit.\n\nThe Client MUST ensure truncation happens at a character boundary to maintain valid\nstring output, even if this means the retained output is slightly less than the\nspecified limit.", @@ -1393,11 +1474,10 @@ "null" ], "format": "uint64", - "minimum": 0, - "x-deserialize-default-on-error": true + "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -1426,7 +1506,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -1461,7 +1541,7 @@ ] }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -1498,7 +1578,7 @@ ] }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -1535,7 +1615,7 @@ ] }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -1572,7 +1652,7 @@ ] }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -1597,7 +1677,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -1714,7 +1794,7 @@ "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.", + "description": "Session-scoped elicitation, optionally tied to a specific tool call.\n\nWhen `toolCallId` 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": { @@ -1808,7 +1888,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -1829,7 +1909,7 @@ ] }, "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.", + "description": "Property schema for elicitation form fields.\n\nEach variant corresponds to a JSON Schema `\"type\"` value.\nSingle-select enums use `type: \"string\"` with `enum` or `oneOf` set.\nMulti-select enums use `type: \"array\"`.", "anyOf": [ { "description": "String property (or single-select enum when `enum`/`oneOf` is set).", @@ -2048,7 +2128,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -2147,7 +2227,7 @@ } }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -2203,7 +2283,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -2259,7 +2339,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -2298,7 +2378,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -2362,7 +2442,7 @@ }, { "title": "titled", - "description": "Titled multi-select items with human-readable labels.", + "description": "Titled multi-select items with human-readable labels.\n\nAs in MCP, titled items omit `type` and are identified by `anyOf`.", "allOf": [ { "$ref": "#/$defs/TitledMultiSelectItems" @@ -2383,7 +2463,7 @@ } }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -2408,7 +2488,7 @@ } }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -2480,7 +2560,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -2610,7 +2690,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -2636,7 +2716,7 @@ "type": "string" }, "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/extensibility)" + "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/v1/draft/extensibility)" }, "AgentResponse": { "description": "A JSON-RPC response object.", @@ -2711,6 +2791,15 @@ } ] }, + { + "title": "AuthStatusResponse", + "description": "Successful result returned for an `auth/status` request.", + "allOf": [ + { + "$ref": "#/$defs/AuthStatusResponse" + } + ] + }, { "title": "NewSessionResponse", "description": "Successful result returned for a `session/new` request.", @@ -2757,74 +2846,92 @@ ] }, { - "title": "ResumeSessionResponse", - "description": "Successful result returned for a `session/resume` request.", + "title": "ArchiveSessionResponse", + "description": "Successful result returned for a `session/archive` request.", "allOf": [ { - "$ref": "#/$defs/ResumeSessionResponse" + "$ref": "#/$defs/ArchiveSessionResponse" } ] }, { - "title": "CloseSessionResponse", - "description": "Successful result returned for a `session/close` request.", + "title": "UnarchiveSessionResponse", + "description": "Successful result returned for a `session/unarchive` request.", "allOf": [ { - "$ref": "#/$defs/CloseSessionResponse" + "$ref": "#/$defs/UnarchiveSessionResponse" } ] }, { - "title": "SetSessionModeResponse", - "description": "Successful result returned for a `session/set_mode` request.", + "title": "SessionStatusResponse", + "description": "Successful result returned for a `session/status` request.", "allOf": [ { - "$ref": "#/$defs/SetSessionModeResponse" + "$ref": "#/$defs/SessionStatusResponse" } ] }, { - "title": "SetSessionConfigOptionResponse", - "description": "Successful result returned for a `session/set_config_option` request.", + "title": "SessionOptionsResponse", + "description": "Successful result returned for a `session/options` request.", "allOf": [ { - "$ref": "#/$defs/SetSessionConfigOptionResponse" + "$ref": "#/$defs/SessionOptionsResponse" } ] }, { - "title": "PromptResponse", - "description": "Successful result returned for a `session/prompt` request.", + "title": "SetSessionTitleResponse", + "description": "Successful result returned for a `session/set_title` request.", "allOf": [ { - "$ref": "#/$defs/PromptResponse" + "$ref": "#/$defs/SetSessionTitleResponse" + } + ] + }, + { + "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": "StartNesResponse", - "description": "Successful result returned for a `nes/start` request.", + "title": "SetSessionModeResponse", + "description": "Successful result returned for a `session/set_mode` request.", "allOf": [ { - "$ref": "#/$defs/StartNesResponse" + "$ref": "#/$defs/SetSessionModeResponse" } ] }, { - "title": "SuggestNesResponse", - "description": "Successful result returned for a `nes/suggest` request.", + "title": "SetSessionConfigOptionResponse", + "description": "Successful result returned for a `session/set_config_option` request.", "allOf": [ { - "$ref": "#/$defs/SuggestNesResponse" + "$ref": "#/$defs/SetSessionConfigOptionResponse" } ] }, { - "title": "CloseNesResponse", - "description": "Successful result returned for a `nes/close` request.", + "title": "PromptResponse", + "description": "Successful result returned for a `session/prompt` request.", "allOf": [ { - "$ref": "#/$defs/CloseNesResponse" + "$ref": "#/$defs/PromptResponse" } ] }, @@ -2876,7 +2983,7 @@ "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/initialization)", + "description": "Response to the `initialize` method.\n\nContains the negotiated protocol version and agent capabilities.\n\nSee protocol docs: [Initialization](https://agentclientprotocol.com/protocol/v1/draft/initialization)", "type": "object", "properties": { "protocolVersion": { @@ -2934,7 +3041,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -2957,7 +3064,7 @@ "maximum": 65535 }, "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/initialization#agent-capabilities)", + "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/v1/draft/initialization#agent-capabilities)", "type": "object", "properties": { "loadSession": { @@ -3026,32 +3133,8 @@ ], "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3062,29 +3145,29 @@ } }, "PromptCapabilities": { - "description": "Prompt capabilities supported by the agent in `session/prompt` requests.\n\nBaseline agent functionality requires support for [`ContentBlock::Text`]\nand [`ContentBlock::ResourceLink`] in prompt requests.\n\nOther variants must be explicitly opted in to.\nCapabilities for different types of content in prompt requests.\n\nIndicates which content types beyond the baseline (text and resource links)\nthe agent can process.\n\nSee protocol docs: [Prompt Capabilities](https://agentclientprotocol.com/protocol/initialization#prompt-capabilities)", + "description": "Prompt capabilities supported by the agent in `session/prompt` requests.\n\nBaseline agent functionality requires support for `text`\nand `resource_link` content blocks 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/v1/draft/initialization#prompt-capabilities)", "type": "object", "properties": { "image": { - "description": "Agent supports [`ContentBlock::Image`].", + "description": "Agent supports `image` content blocks.", "type": "boolean", "default": false, "x-deserialize-default-on-error": true }, "audio": { - "description": "Agent supports [`ContentBlock::Audio`].", + "description": "Agent supports `audio` content blocks.", "type": "boolean", "default": false, "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.", + "description": "Agent supports embedded context in `session/prompt` requests.\n\nWhen enabled, the Client is allowed to include `resource` content blocks\nin prompt requests for pieces of context that are referenced in the message.", "type": "boolean", "default": false, "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3099,25 +3182,25 @@ "type": "object", "properties": { "http": { - "description": "Agent supports [`McpServer::Http`].", + "description": "Agent supports `http` MCP servers.", "type": "boolean", "default": false, "x-deserialize-default-on-error": true }, "sse": { - "description": "Agent supports [`McpServer::Sse`].", + "description": "Agent supports `sse` MCP servers.", "type": "boolean", "default": false, "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`].", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAgent supports `acp` MCP servers.", "type": "boolean", "default": false, "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3128,7 +3211,7 @@ } }, "SessionCapabilities": { - "description": "Session capabilities supported by the agent.\n\nAs a baseline, all Agents **MUST** support `session/new`, `session/prompt`, `session/cancel`, and `session/update`.\n\nOptionally, they **MAY** support other session methods and notifications by specifying additional capabilities.\n\nNote: `session/load` is still handled by the top-level `load_session` capability. This will be unified in future versions of the protocol.\n\nSee protocol docs: [Session Capabilities](https://agentclientprotocol.com/protocol/initialization#session-capabilities)", + "description": "Session capabilities supported by the agent.\n\nAs a baseline, all Agents **MUST** support `session/new`, `session/prompt`, `session/cancel`, and `session/update`.\n\nOptionally, they **MAY** support other session methods and notifications by specifying additional capabilities.\n\nNote: `session/load` is still handled by the top-level `loadSession` capability. This will be unified in future versions of the protocol.\n\nSee protocol docs: [Session Capabilities](https://agentclientprotocol.com/protocol/v1/draft/initialization#session-capabilities)", "type": "object", "properties": { "list": { @@ -3167,6 +3250,18 @@ ], "x-deserialize-default-on-error": true }, + "systemPrompt": { + "description": "Whether the agent supports `systemPrompt` on session lifecycle requests.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports `systemPrompt` in `append` mode.", + "anyOf": [ + { + "$ref": "#/$defs/SessionSystemPromptCapabilities" + }, + { + "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": [ @@ -3179,6 +3274,54 @@ ], "x-deserialize-default-on-error": true }, + "archive": { + "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/archive` and `session/unarchive`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports both methods, the `archived` filter on\n`session/list`, and `SessionInfo.archived`. Agents that advertise it MUST also advertise `sessionCapabilities.list`.", + "anyOf": [ + { + "$ref": "#/$defs/SessionArchiveCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "status": { + "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/status`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports checking session status.", + "anyOf": [ + { + "$ref": "#/$defs/SessionStatusCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "options": { + "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/options`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports `session/options` and accepts initial\nconfig option values on session setup requests.", + "anyOf": [ + { + "$ref": "#/$defs/SessionOptionsCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "title": { + "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/set_title`.\n\nAgents report titles through `session/list` and `session_info_update` without this\ncapability. It only advertises that Clients can set titles.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports setting session titles.", + "anyOf": [ + { + "$ref": "#/$defs/SessionTitleCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, "resume": { "description": "Whether the agent supports `session/resume`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports resuming sessions.", "anyOf": [ @@ -3204,7 +3347,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3219,7 +3362,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3234,7 +3377,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3249,7 +3392,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3259,12 +3402,24 @@ } } }, - "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.", + "SessionSystemPromptCapabilities": { + "description": "Capabilities for client-provided system prompts.\n\nSupplying `{}` means the agent supports `systemPrompt` on session lifecycle\nrequests in `append` mode.", "type": "object", "properties": { + "mode": { + "description": "Delivery modes the agent supports in addition to `append`.\n\nOptional. Omitted or `null` both mean the agent supports only `append`.", + "anyOf": [ + { + "$ref": "#/$defs/SessionSystemPromptModeCapabilities" + }, + { + "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3274,12 +3429,24 @@ } } }, - "SessionResumeCapabilities": { - "description": "Capabilities for the `session/resume` method.\n\nSupplying `{}` means the agent supports resuming sessions.", + "SessionSystemPromptModeCapabilities": { + "description": "System prompt delivery modes the agent supports in addition to `append`.\n\n`append` has no entry because every agent advertising\n`sessionCapabilities.systemPrompt` supports it.", "type": "object", "properties": { + "override": { + "description": "Whether the agent supports `override` mode.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports replacing its built-in default\ninstructions with the client-provided system prompt.", + "anyOf": [ + { + "$ref": "#/$defs/SessionSystemPromptOverrideCapabilities" + }, + { + "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3289,12 +3456,12 @@ } } }, - "SessionCloseCapabilities": { - "description": "Capabilities for the `session/close` method.\n\nSupplying `{}` means the agent supports closing sessions.", + "SessionSystemPromptOverrideCapabilities": { + "description": "Capabilities for the `override` system prompt mode.\n\nSupplying `{}` means the agent supports replacing its built-in default\ninstructions with the client-provided system prompt.", "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3304,24 +3471,12 @@ } } }, - "AgentAuthCapabilities": { - "description": "Authentication-related capabilities supported by the agent.", + "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": { - "logout": { - "description": "Whether the agent supports the logout method.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports the logout method.", - "anyOf": [ - { - "$ref": "#/$defs/LogoutCapabilities" - }, - { - "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3331,12 +3486,12 @@ } } }, - "LogoutCapabilities": { - "description": "Logout capabilities supported by the agent.\n\nSupplying `{}` means the agent supports the logout method.", + "SessionArchiveCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapabilities for `session/archive` and `session/unarchive`.\n\nSupplying `{}` means the agent supports both methods, the `archived` filter on\n`session/list`, and `SessionInfo.archived`.", "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3346,12 +3501,12 @@ } } }, - "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.", + "SessionStatusCapabilities": { + "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/status` method.\n\nSupplying `{}` means the agent supports checking session status.", "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3361,153 +3516,12 @@ } } }, - "NesCapabilities": { - "description": "NES capabilities advertised by the agent during initialization.", - "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/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/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/extensibility)", - "type": [ - "object", - "null" - ], - "x-deserialize-default-on-error": true, - "additionalProperties": true - } - } - }, - "NesDocumentDidOpenCapabilities": { - "description": "Marker for `document/didOpen` capability support.", + "SessionOptionsCapabilities": { + "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/options` method.\n\nSupplying `{}` means the agent supports `session/options` and accepts initial config\noption values on session setup requests.", "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3517,53 +3531,12 @@ } } }, - "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/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.", + "SessionTitleCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapabilities for Client-set session titles.\n\nSupplying `{}` means the agent supports `session/set_title`. Agents report titles\nthrough `session/list` and `session_info_update` without this capability.", "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3573,12 +3546,12 @@ } } }, - "NesDocumentDidSaveCapabilities": { - "description": "Marker for `document/didSave` capability support.", + "SessionResumeCapabilities": { + "description": "Capabilities for the `session/resume` method.\n\nSupplying `{}` means the agent supports resuming 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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3588,12 +3561,12 @@ } } }, - "NesDocumentDidFocusCapabilities": { - "description": "Marker for `document/didFocus` capability support.", + "SessionCloseCapabilities": { + "description": "Capabilities for the `session/close` method.\n\nSupplying `{}` means the agent supports closing 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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3603,63 +3576,15 @@ } } }, - "NesContextCapabilities": { - "description": "Context capabilities the agent wants attached to each suggestion request.", + "AgentAuthCapabilities": { + "description": "Authentication-related capabilities supported by the agent.", "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.", + "status": { + "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 the `auth/status` method.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports the `auth/status` method.", "anyOf": [ { - "$ref": "#/$defs/NesOpenFilesCapabilities" + "$ref": "#/$defs/AuthStatusCapabilities" }, { "type": "null" @@ -3667,11 +3592,11 @@ ], "x-deserialize-default-on-error": true }, - "diagnostics": { - "description": "Whether the agent wants diagnostics context.", + "logout": { + "description": "Whether the agent supports the logout method.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports the logout method.", "anyOf": [ { - "$ref": "#/$defs/NesDiagnosticsCapabilities" + "$ref": "#/$defs/LogoutCapabilities" }, { "type": "null" @@ -3680,72 +3605,7 @@ "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/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/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/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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3755,22 +3615,12 @@ } } }, - "NesUserActionsCapabilities": { - "description": "Capabilities for user actions context.", + "AuthStatusCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAuth status capabilities supported by the agent.\n\nSupplying `{}` means the agent supports the `auth/status` method.", "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3780,12 +3630,12 @@ } } }, - "NesOpenFilesCapabilities": { - "description": "Capabilities for open files context.", + "LogoutCapabilities": { + "description": "Logout capabilities supported by the agent.\n\nSupplying `{}` means the agent supports the 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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3795,12 +3645,12 @@ } } }, - "NesDiagnosticsCapabilities": { - "description": "Capabilities for diagnostics context.", + "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3810,26 +3660,6 @@ } } }, - "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.\nWhen no `type` is present, the method is treated as `agent`.", "anyOf": [ @@ -3867,7 +3697,7 @@ "type": "string" }, "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 `authenticate`.", + "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 `authenticate`.", "type": "object", "properties": { "id": { @@ -3883,7 +3713,7 @@ "type": "string" }, "description": { - "description": "Optional description providing more details about this authentication method.", + "description": "Optional human-readable description of this authentication method.", "type": [ "string", "null" @@ -3896,19 +3726,18 @@ "items": { "type": "string" }, - "x-deserialize-default-on-error": true, - "x-deserialize-skip-invalid-items": true + "x-deserialize-default-on-null": true }, "env": { "description": "Additional environment variables to set on the configured agent invocation for terminal auth.\nThese values override same-named variables in the base launch configuration.", "type": "object", - "x-deserialize-default-on-error": true, + "x-deserialize-default-on-null": true, "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3939,7 +3768,7 @@ "type": "string" }, "description": { - "description": "Optional description providing more details about this authentication method.", + "description": "Optional human-readable description of this authentication method.", "type": [ "string", "null" @@ -3947,7 +3776,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -3966,11 +3795,11 @@ "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.", + "description": "Intended for programmatic or logical use, but can be used as a display\nname fallback if title isn't 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.", + "description": "Intended for UI and end-user contexts and optimized to be human-readable\nand easily understood.\n\nIf not provided, the name should be used for display.", "type": [ "string", "null" @@ -3982,7 +3811,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4001,7 +3830,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4025,7 +3854,7 @@ } }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4077,7 +3906,7 @@ ] }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4148,7 +3977,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4167,7 +3996,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4184,7 +4013,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4201,7 +4030,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4213,11 +4042,140 @@ "x-side": "agent", "x-method": "logout" }, - "NewSessionResponse": { - "description": "Response from creating a new session.\n\nSee protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/session-setup#creating-a-session)", + "AuthStatusResponse": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse to the `auth/status` method.", "type": "object", "properties": { - "sessionId": { + "state": { + "description": "Whether the agent can start sessions without the user signing in first.\n\nClients use this field to decide whether sign-in is needed. Clients MUST treat\nvalues they do not recognize as `unknown`.", + "allOf": [ + { + "$ref": "#/$defs/AuthState" + } + ] + }, + "accounts": { + "description": "The accounts the agent has configured, for display.\n\nOptional. Omitted and empty are equivalent and mean no accounts are reported.\nAgents that hold credentials for several providers or accounts SHOULD list each\nof them and mark the ones in effect with `active`.", + "type": "array", + "items": { + "$ref": "#/$defs/AuthAccount" + }, + "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/v1/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "state" + ], + "x-side": "agent", + "x-method": "auth/status" + }, + "AuthState": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe agent's overall authentication state.", + "anyOf": [ + { + "description": "Credentials are configured. This does not guarantee that they are valid.", + "type": "string", + "const": "authenticated" + }, + { + "description": "The user needs to sign in. This includes credentials that are missing,\nexpired, or known to be invalid.", + "type": "string", + "const": "unauthenticated" + }, + { + "description": "No authentication is needed, for example because the agent uses a local model.", + "type": "string", + "const": "not_required" + }, + { + "description": "The agent cannot currently determine the state.", + "type": "string", + "const": "unknown" + }, + { + "title": "other", + "description": "Custom or future authentication 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" + } + ] + }, + "AuthAccount": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAn account or credential the agent has configured, such as a signed-in user\naccount or an API key.\n\nAll fields are display information only. Clients MUST NOT use them as stable\naccount identifiers, and SHOULD NOT log them or send them elsewhere, such as to\ntelemetry.", + "type": "object", + "properties": { + "label": { + "description": "Human-readable name for the account, suitable for display on its own,\nfor example `Claude Max`, `OpenAI API key`, or `Vertex AI`.", + "type": "string" + }, + "description": { + "description": "Short text shown with the label, such as the credential source, for example\n`API key helper`. MUST NOT contain credentials.\n\nOptional. Omitted and `null` are equivalent and mean no description is reported.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "active": { + "description": "Whether the agent currently uses this account by default.\n\nSeveral accounts MAY be active, for example one per provider.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not indicate whether this account is in effect.", + "type": [ + "boolean", + "null" + ], + "x-deserialize-default-on-error": true + }, + "name": { + "description": "Display name of the user, such as a username or full name.\n\nOptional. Omitted and `null` are equivalent and mean no name is reported.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "email": { + "description": "Email address of the user.\n\nOptional. Omitted and `null` are equivalent and mean no email is reported.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true + }, + "organization": { + "description": "Display name of the organization, team, or workspace the account is using.\n\nOptional. Omitted and `null` are equivalent and mean no organization is reported.", + "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/v1/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "label" + ] + }, + "NewSessionResponse": { + "description": "Response from creating a new session.\n\nSee protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/v1/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": [ { @@ -4226,7 +4184,7 @@ ] }, "modes": { - "description": "Initial mode state if supported by the Agent\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)", + "description": "Initial mode state if supported by the Agent\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/draft/session-modes)", "anyOf": [ { "$ref": "#/$defs/SessionModeState" @@ -4250,7 +4208,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4287,7 +4245,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4306,7 +4264,7 @@ "type": "string" }, "SessionMode": { - "description": "A mode the agent can operate in.\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)", + "description": "A mode the agent can operate in.\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/draft/session-modes)", "type": "object", "properties": { "id": { @@ -4330,7 +4288,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4381,7 +4339,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4458,6 +4416,11 @@ "type": "string", "const": "model_config" }, + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse speed selector, such as a fast mode toggle.", + "type": "string", + "const": "speed" + }, { "description": "Thought/reasoning level selector.", "type": "string", @@ -4520,7 +4483,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4560,7 +4523,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4623,7 +4586,7 @@ "type": "object", "properties": { "modes": { - "description": "Initial mode state if supported by the Agent\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)", + "description": "Initial mode state if supported by the Agent\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/draft/session-modes)", "anyOf": [ { "$ref": "#/$defs/SessionModeState" @@ -4647,7 +4610,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4681,7 +4644,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4737,8 +4700,16 @@ ], "x-deserialize-default-on-error": true }, + "archived": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhether the session is archived.\n\nOptional. Omitted and `null` are equivalent and mean the archive state is not reported.\nAgents that advertise the `sessionCapabilities.archive` capability MUST include it on every listed session.", + "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\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4757,7 +4728,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4782,7 +4753,7 @@ ] }, "modes": { - "description": "Initial mode state if supported by the Agent\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)", + "description": "Initial mode state if supported by the Agent\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/draft/session-modes)", "anyOf": [ { "$ref": "#/$defs/SessionModeState" @@ -4806,7 +4777,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4821,12 +4792,159 @@ "x-side": "agent", "x-method": "session/fork" }, + "ArchiveSessionResponse": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse from archiving 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/v1/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "x-side": "agent", + "x-method": "session/archive" + }, + "UnarchiveSessionResponse": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse from unarchiving 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/v1/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "x-side": "agent", + "x-method": "session/unarchive" + }, + "SessionStatusResponse": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse from checking the status of a session.\n\nThe result is a snapshot. A session reported `open` may be closed or evicted before\nthe Client's next request.", + "type": "object", + "properties": { + "status": { + "description": "Whether the Agent has the session in memory.\n\nRequired. Clients MUST treat a value they do not recognize as `saved`.", + "allOf": [ + { + "$ref": "#/$defs/SessionStatus" + } + ] + }, + "_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/v1/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "status" + ], + "x-side": "agent", + "x-method": "session/status" + }, + "SessionStatus": { + "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 has a session in memory, as reported by `session/status`.", + "anyOf": [ + { + "description": "The Agent has the session in memory, for any connection.\n\nThis does not mean the requesting connection is attached to it. A Client that did\nnot create or resume the session on its own connection MUST still call\n`session/load` or `session/resume` before sending `session/prompt` or expecting\n`session/update` notifications.", + "type": "string", + "const": "open" + }, + { + "description": "The Agent knows the session and can resume it, but does not have it in memory.\n\nThe Client can call `session/load` or `session/resume` to start it.", + "type": "string", + "const": "saved" + }, + { + "title": "other", + "description": "Custom or future session status.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants. Clients MUST treat a value they do not recognize as\n`saved`.", + "type": "string" + } + ] + }, + "SessionOptionsResponse": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse from `session/options`.\n\nThe result is a snapshot. The options a session actually starts with are the ones in\nthe session setup response.\n\nAgents only return `type: \"boolean\"` options when the Client advertises\n`sessionCapabilities.configOptions.boolean`.", + "type": "object", + "properties": { + "modes": { + "description": "The mode state the session would start with, if the Agent supports modes.\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/draft/session-modes)", + "anyOf": [ + { + "$ref": "#/$defs/SessionModeState" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "configOptions": { + "description": "The config options the session would start with, with the same rules as on\n`NewSessionResponse`.\n\nOptional. Omitted, `null`, or empty means no config options are advertised.", + "type": [ + "array", + "null" + ], + "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/v1/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "x-side": "agent", + "x-method": "session/options" + }, + "SetSessionTitleResponse": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse from setting the title of a session.", + "type": "object", + "properties": { + "title": { + "description": "The title the Agent stored.\n\nThis differs from the requested title if the Agent normalized it. Clients SHOULD\ndisplay this value rather than the one they sent.", + "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/v1/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "title" + ], + "x-side": "agent", + "x-method": "session/set_title" + }, "ResumeSessionResponse": { "description": "Response from resuming an existing session.", "type": "object", "properties": { "modes": { - "description": "Initial mode state if supported by the Agent\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)", + "description": "Initial mode state if supported by the Agent\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/draft/session-modes)", "anyOf": [ { "$ref": "#/$defs/SessionModeState" @@ -4850,7 +4968,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4867,7 +4985,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4884,7 +5002,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4910,7 +5028,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4926,7 +5044,7 @@ "x-method": "session/set_config_option" }, "PromptResponse": { - "description": "Response from processing a user prompt.\n\nSee protocol docs: [Check for Completion](https://agentclientprotocol.com/protocol/prompt-turn#4-check-for-completion)", + "description": "Response from processing a user prompt.\n\nSee protocol docs: [Check for Completion](https://agentclientprotocol.com/protocol/v1/draft/prompt-turn#4-check-for-completion)", "type": "object", "properties": { "stopReason": { @@ -4950,7 +5068,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -4966,7 +5084,7 @@ "x-method": "session/prompt" }, "StopReason": { - "description": "Reasons why an agent stops processing a prompt turn.\n\nSee protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/prompt-turn#stop-reasons)", + "description": "Reasons why an agent stops processing a prompt turn.\n\nSee protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/v1/draft/prompt-turn#stop-reasons)", "oneOf": [ { "description": "The turn ended successfully.", @@ -5048,7 +5166,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -5063,47 +5181,187 @@ "outputTokens" ] }, - "StartNesResponse": { - "description": "Response to `nes/start`.", + "ExtResponse": { + "description": "Allows for sending an arbitrary response to an extension 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/v1/draft/extensibility)" + }, + "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": { - "sessionId": { - "description": "The session ID for the newly started NES session.", + "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/SessionId" + "$ref": "#/$defs/ErrorCode" } ] }, - "_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/extensibility)", - "type": [ - "object", - "null" - ], - "x-deserialize-default-on-error": true, - "additionalProperties": true + "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": [ - "sessionId" - ], - "x-side": "agent", - "x-method": "nes/start" + "code", + "message" + ] }, - "SuggestNesResponse": { - "description": "Response to `nes/suggest`.", - "type": "object", - "properties": { - "suggestions": { - "description": "The list of suggestions.", - "type": "array", - "items": { - "$ref": "#/$defs/NesSuggestion" - } - }, + "ErrorCode": { + "description": "Predefined error codes for common JSON-RPC and ACP-specific errors.\n\nStandard errors use the JSON-RPC 2.0 codes. ACP-specific errors use the JSON-RPC\nserver-error range (-32000 to -32099), and request cancellation uses -32800 from the\nrange LSP reserves (-32899 to -32800).", + "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.", + "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 session or 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": "SessionNotification", + "description": "Handles session update notifications from the agent.\n\nThis is a notification endpoint (no response expected) that receives\nreal-time updates about session progress, including 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 responding with the cancelled stop reason.\n\nSee protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/v1/draft/prompt-turn#3-agent-reports-output)", + "allOf": [ + { + "$ref": "#/$defs/SessionNotification" + } + ] + }, + { + "title": "CompleteElicitationNotification", + "description": "Notification that a URL-based elicitation has completed.\n\nSee protocol docs: [Elicitation](https://agentclientprotocol.com/protocol/v1/draft/elicitation#url-completion)", + "allOf": [ + { + "$ref": "#/$defs/CompleteElicitationNotification" + } + ] + }, + { + "title": "AuthStatusUpdateNotification", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nNotification that the agent's authentication state changed.\n\nOnly sent by agents that advertise the `auth.status` capability.", + "allOf": [ + { + "$ref": "#/$defs/AuthStatusUpdateNotification" + } + ] + }, + { + "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/v1/draft/extensibility)", + "allOf": [ + { + "$ref": "#/$defs/ExtNotification" + } + ] + } + ] + }, + { + "type": "null" + } + ] + } + }, + "required": [ + "method" + ], + "x-docs-ignore": true + }, + "SessionNotification": { + "description": "Notification containing a session update from the agent.\n\nUsed to stream real-time progress and results during prompt processing.\n\nSee protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/v1/draft/prompt-turn#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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -5113,720 +5371,152 @@ } }, "required": [ - "suggestions" + "sessionId", + "update" ], - "x-side": "agent", - "x-method": "nes/suggest" + "x-side": "client", + "x-method": "session/update" }, - "NesSuggestion": { - "description": "A suggestion returned by the agent.", + "SessionUpdate": { + "description": "Different types of updates that can be sent during session processing.\n\nThese updates provide real-time feedback about the agent's progress.\n\nSee protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/v1/draft/prompt-turn#3-agent-reports-output)", "oneOf": [ { - "description": "A text edit suggestion.", + "description": "A chunk of the user's message being streamed.", "type": "object", "properties": { - "kind": { + "sessionUpdate": { "type": "string", - "const": "edit" + "const": "user_message_chunk" } }, "required": [ - "kind" + "sessionUpdate" ], "allOf": [ { - "$ref": "#/$defs/NesEditSuggestion" + "$ref": "#/$defs/ContentChunk" } ] }, { - "description": "A jump-to-location suggestion.", + "description": "A chunk of the agent's response being streamed.", "type": "object", "properties": { - "kind": { + "sessionUpdate": { "type": "string", - "const": "jump" + "const": "agent_message_chunk" } }, "required": [ - "kind" + "sessionUpdate" ], "allOf": [ { - "$ref": "#/$defs/NesJumpSuggestion" + "$ref": "#/$defs/ContentChunk" } ] }, { - "description": "A rename symbol suggestion.", + "description": "A chunk of the agent's internal reasoning being streamed.", "type": "object", "properties": { - "kind": { + "sessionUpdate": { "type": "string", - "const": "rename" + "const": "agent_thought_chunk" } }, "required": [ - "kind" + "sessionUpdate" ], "allOf": [ { - "$ref": "#/$defs/NesRenameSuggestion" + "$ref": "#/$defs/ContentChunk" } ] }, { - "description": "A search-and-replace suggestion.", + "description": "Notification that a new tool call has been initiated.", "type": "object", "properties": { - "kind": { + "sessionUpdate": { "type": "string", - "const": "searchAndReplace" + "const": "tool_call" } }, "required": [ - "kind" + "sessionUpdate" ], "allOf": [ { - "$ref": "#/$defs/NesSearchAndReplaceSuggestion" + "$ref": "#/$defs/ToolCall" } ] - } - ], - "discriminator": { - "propertyName": "kind" - } - }, - "NesSuggestionId": { - "description": "Unique identifier for a next edit suggestion.", - "type": "string" - }, - "NesTextEdit": { - "description": "A text edit within a suggestion.", - "type": "object", - "properties": { - "range": { - "description": "The range to replace.", + }, + { + "description": "Update on the status or results of a tool call.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "tool_call_update" + } + }, + "required": [ + "sessionUpdate" + ], "allOf": [ { - "$ref": "#/$defs/Range" + "$ref": "#/$defs/ToolCallUpdate" } ] }, - "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/extensibility)", - "type": [ - "object", - "null" + { + "description": "The agent's execution plan for complex tasks.\nSee protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/v1/draft/agent-plan)", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "plan" + } + }, + "required": [ + "sessionUpdate" ], - "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" + "$ref": "#/$defs/Plan" } ] }, - "end": { - "description": "The end position (exclusive).", + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA content update for a plan identified by ID.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "plan_update" + } + }, + "required": [ + "sessionUpdate" + ], "allOf": [ { - "$ref": "#/$defs/Position" + "$ref": "#/$defs/PlanUpdate" } ] }, - "_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/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/extensibility)", - "type": [ - "object", - "null" - ], - "x-deserialize-default-on-error": true, - "additionalProperties": true - } - }, - "required": [ - "line", - "character" - ] - }, - "NesEditSuggestion": { - "description": "A text edit suggestion.", - "type": "object", - "properties": { - "id": { - "description": "Unique identifier for accept/reject tracking.", - "allOf": [ - { - "$ref": "#/$defs/NesSuggestionId" - } - ] - }, - "uri": { - "description": "The URI of the file to edit.", - "type": "string" - }, - "edits": { - "description": "The text edits to apply.", - "type": "array", - "items": { - "$ref": "#/$defs/NesTextEdit" - } - }, - "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/extensibility)", - "type": [ - "object", - "null" - ], - "x-deserialize-default-on-error": true, - "additionalProperties": true - } - }, - "required": [ - "id", - "uri", - "edits" - ] - }, - "NesJumpSuggestion": { - "description": "A jump-to-location suggestion.", - "type": "object", - "properties": { - "id": { - "description": "Unique identifier for accept/reject tracking.", - "allOf": [ - { - "$ref": "#/$defs/NesSuggestionId" - } - ] - }, - "uri": { - "description": "The file to navigate to.", - "type": "string" - }, - "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/extensibility)", - "type": [ - "object", - "null" - ], - "x-deserialize-default-on-error": true, - "additionalProperties": true - } - }, - "required": [ - "id", - "uri", - "position" - ] - }, - "NesRenameSuggestion": { - "description": "A rename symbol suggestion.", - "type": "object", - "properties": { - "id": { - "description": "Unique identifier for accept/reject tracking.", - "allOf": [ - { - "$ref": "#/$defs/NesSuggestionId" - } - ] - }, - "uri": { - "description": "The file URI containing the symbol.", - "type": "string" - }, - "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/extensibility)", - "type": [ - "object", - "null" - ], - "x-deserialize-default-on-error": true, - "additionalProperties": true - } - }, - "required": [ - "id", - "uri", - "position", - "newName" - ] - }, - "NesSearchAndReplaceSuggestion": { - "description": "A search-and-replace suggestion.", - "type": "object", - "properties": { - "id": { - "description": "Unique identifier for accept/reject tracking.", - "allOf": [ - { - "$ref": "#/$defs/NesSuggestionId" - } - ] - }, - "uri": { - "description": "The file URI to search within.", - "type": "string" - }, - "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/extensibility)", - "type": [ - "object", - "null" - ], - "x-deserialize-default-on-error": true, - "additionalProperties": true - } - }, - "required": [ - "id", - "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/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/extensibility)" - }, - "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": "SessionNotification", - "description": "Handles session update notifications from the agent.\n\nThis is a notification endpoint (no response expected) that receives\nreal-time updates about session progress, including 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 responding with the cancelled stop reason.\n\nSee protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output)", - "allOf": [ - { - "$ref": "#/$defs/SessionNotification" - } - ] - }, - { - "title": "CompleteElicitationNotification", - "description": "Notification that a URL-based elicitation has completed.\n\nSee protocol docs: [Elicitation](https://agentclientprotocol.com/protocol/elicitation#url-completion)", - "allOf": [ - { - "$ref": "#/$defs/CompleteElicitationNotification" - } - ] - }, - { - "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/extensibility)", - "allOf": [ - { - "$ref": "#/$defs/ExtNotification" - } - ] - } - ] - }, - { - "type": "null" - } - ] - } - }, - "required": [ - "method" - ], - "x-docs-ignore": true - }, - "SessionNotification": { - "description": "Notification containing a session update from the agent.\n\nUsed to stream real-time progress and results during prompt processing.\n\nSee protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#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/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 during session processing.\n\nThese updates provide real-time feedback about the agent's progress.\n\nSee protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output)", - "oneOf": [ - { - "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 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": "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": "Notification that a new tool call has been initiated.", - "type": "object", - "properties": { - "sessionUpdate": { - "type": "string", - "const": "tool_call" - } - }, - "required": [ - "sessionUpdate" - ], - "allOf": [ - { - "$ref": "#/$defs/ToolCall" - } - ] - }, - { - "description": "Update on the status or results of a tool call.", - "type": "object", - "properties": { - "sessionUpdate": { - "type": "string", - "const": "tool_call_update" - } - }, - "required": [ - "sessionUpdate" - ], - "allOf": [ - { - "$ref": "#/$defs/ToolCallUpdate" - } - ] - }, - { - "description": "The agent's execution plan for complex tasks.\nSee protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/agent-plan)", - "type": "object", - "properties": { - "sessionUpdate": { - "type": "string", - "const": "plan" - } - }, - "required": [ - "sessionUpdate" - ], - "allOf": [ - { - "$ref": "#/$defs/Plan" - } - ] - }, - { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA content update for a plan identified by ID.", - "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" + { + "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": [ { @@ -5853,7 +5543,7 @@ ] }, { - "description": "The current mode of the session has changed\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)", + "description": "The current mode of the session has changed\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/draft/session-modes)", "type": "object", "properties": { "sessionUpdate": { @@ -5925,7 +5615,7 @@ ] }, { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAdvisory information for the user that is not part of session history.\n\nAgents MUST only send this update when the Client advertised\n[`ClientSessionCapabilities::notices`].", + "description": "Information for the user that is not part of session history.\n\nAgents MUST only send this update when the Client advertised\nthe `session.notices` Client capability.", "type": "object", "properties": { "sessionUpdate": { @@ -5943,7 +5633,7 @@ ] }, { - "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.\n\nAgents MUST only send this update when the Client advertised\n[`ClientSessionCapabilities::compaction`].", + "description": "A context compaction has been created or updated.\n\nAgents MUST only send this update when the Client advertised\nthe `session.compaction` Client capability.", "type": "object", "properties": { "sessionUpdate": { @@ -5961,7 +5651,7 @@ ] }, { - "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.\n\nAgents MUST only send this update when the Client advertised\n[`ClientSessionCapabilities::compaction`].", + "description": "A content block appended to a context compaction's retained summary.\n\nAgents MUST only send this update when the Client advertised\nthe `session.compaction` Client capability.", "type": "object", "properties": { "sessionUpdate": { @@ -5978,6 +5668,42 @@ } ] }, + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nReplaces the session's current list of prompt suggestions.\n\nAgents MUST only send this update when the Client advertised\nthe `session.promptSuggestions` Client capability.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "prompt_suggestions_update" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/PromptSuggestionsUpdate" + } + ] + }, + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA session cursor has been announced or its capabilities have changed.\n\nAgents MUST only send this update when the Client advertised\nthe `session.cursors` Client capability.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "cursor_update" + } + }, + "required": [ + "sessionUpdate" + ], + "allOf": [ + { + "$ref": "#/$defs/CursorUpdate" + } + ] + }, { "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAnnounces a child session created and owned by this session, or updates\nthat ownership association's metadata.", "type": "object", @@ -6066,7 +5792,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -6080,7 +5806,7 @@ ] }, "ToolCall": { - "description": "Represents 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\nSee protocol docs: [Tool Calls](https://agentclientprotocol.com/protocol/tool-calls)", + "description": "Represents 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\nSee protocol docs: [Tool Calls](https://agentclientprotocol.com/protocol/v1/draft/tool-calls)", "type": "object", "properties": { "toolCallId": { @@ -6148,7 +5874,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -6163,7 +5889,7 @@ ] }, "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/agent-plan#plan-entries)", + "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/v1/draft/agent-plan#plan-entries)", "type": "object", "properties": { "content": { @@ -6187,7 +5913,7 @@ ] }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -6203,7 +5929,7 @@ ] }, "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/agent-plan#plan-entries)", + "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/v1/draft/agent-plan#plan-entries)", "oneOf": [ { "description": "High priority task - critical to the overall goal.", @@ -6223,7 +5949,7 @@ ] }, "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/agent-plan#plan-entries)", + "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/v1/draft/agent-plan#plan-entries)", "oneOf": [ { "description": "The task has not started yet.", @@ -6243,7 +5969,7 @@ ] }, "Plan": { - "description": "An execution plan for accomplishing complex tasks.\n\nPlans consist of multiple entries representing individual tasks or goals.\nAgents report plans to clients to provide visibility into their execution strategy.\nPlans can evolve during execution as the agent discovers new requirements or completes tasks.\n\nSee protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/agent-plan)", + "description": "An execution plan for accomplishing complex tasks.\n\nPlans consist of multiple entries representing individual tasks or goals.\nAgents report plans to clients to provide visibility into their execution strategy.\nPlans can evolve during execution as the agent discovers new requirements or completes tasks.\n\nSee protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/v1/draft/agent-plan)", "type": "object", "properties": { "entries": { @@ -6256,7 +5982,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -6291,12 +6017,12 @@ ] }, { - "description": "A URI pointing to a file containing the plan.", + "description": "Raw markdown content for the plan.", "type": "object", "properties": { "type": { "type": "string", - "const": "file" + "const": "markdown" } }, "required": [ @@ -6304,60 +6030,289 @@ ], "allOf": [ { - "$ref": "#/$defs/PlanFile" + "$ref": "#/$defs/PlanMarkdown" + } + ] + } + ], + "discriminator": { + "propertyName": "type" + } + }, + "PlanId": { + "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 plan within a session.", + "type": "string" + }, + "PlanItems": { + "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 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/v1/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "planId", + "entries" + ] + }, + "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" + }, + "path": { + "description": "The absolute path of the file that holds this plan.\n\nThis field is optional. Omitting it or sending `null` both mean that the plan\nhas no file. `content` is the plan to display whether or not `path` is set.\nClients can use `path` to open the file.", + "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/v1/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "planId", + "content" + ] + }, + "PlanUpdate": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA 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/v1/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/v1/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/v1/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": "Raw markdown content for the plan.", - "type": "object", - "properties": { - "type": { - "type": "string", - "const": "markdown" + "title": "unstructured", + "description": "All text that was typed after the command name is provided as input.", + "allOf": [ + { + "$ref": "#/$defs/UnstructuredCommandInput" } + ] + } + ] + }, + "UnstructuredCommandInput": { + "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/v1/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" }, - "required": [ - "type" + "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/v1/draft/extensibility)", + "type": [ + "object", + "null" ], - "allOf": [ - { - "$ref": "#/$defs/PlanMarkdown" - } - ] + "x-deserialize-default-on-error": true, + "additionalProperties": true } - ], - "discriminator": { - "propertyName": "type" - } - }, - "PlanId": { - "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 plan within a session.", - "type": "string" + }, + "required": [ + "availableCommands" + ] }, - "PlanItems": { - "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 structured entries.", + "CurrentModeUpdate": { + "description": "The current mode of the session has changed\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/draft/session-modes)", "type": "object", "properties": { - "planId": { - "description": "The plan ID to update.", + "currentModeId": { + "description": "The ID of the current mode", "allOf": [ { - "$ref": "#/$defs/PlanId" + "$ref": "#/$defs/SessionModeId" } ] }, - "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.", + "_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/v1/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "currentModeId" + ] + }, + "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/PlanEntry" + "$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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -6367,28 +6322,55 @@ } }, "required": [ - "planId", - "entries" + "configOptions" ] }, - "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.", + "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.\nClients can use it to keep session titles and state current.", "type": "object", "properties": { - "planId": { - "description": "The plan ID to update.", - "allOf": [ - { - "$ref": "#/$defs/PlanId" - } - ] + "title": { + "description": "Human-readable title for the session. Set to null to clear.", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true }, - "uri": { - "description": "The URI of the file containing the plan.", + "updatedAt": { + "description": "ISO 8601 timestamp of last activity. Set to null to clear.", + "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/v1/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": "Unit of `amount`: an ISO 4217 currency code (e.g., \"USD\", \"EUR\") for money, or another\nunit such as \"credits\".", "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -6398,28 +6380,40 @@ } }, "required": [ - "planId", - "uri" + "amount", + "currency" ] }, - "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.", + "UsageUpdate": { + "description": "Context window and cost update for a session.", "type": "object", "properties": { - "planId": { - "description": "The plan ID to update.", - "allOf": [ + "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/PlanId" + "$ref": "#/$defs/Cost" + }, + { + "type": "null" } - ] - }, - "content": { - "description": "Markdown content for the plan.", - "type": "string" + ], + "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -6429,24 +6423,62 @@ } }, "required": [ - "planId", - "content" + "used", + "size" ] }, - "PlanUpdate": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA content update for a plan identified by ID.", + "NoticeSeverity": { + "description": "Severity hint for a session notice.", + "anyOf": [ + { + "description": "Informational notice.", + "type": "string", + "const": "info" + }, + { + "description": "Warning notice.", + "type": "string", + "const": "warning" + }, + { + "description": "Error notice.", + "type": "string", + "const": "error" + }, + { + "title": "other", + "description": "Custom or future notice severity.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Other unknown values are reserved for future ACP severities.", + "type": "string" + } + ] + }, + "Notice": { + "description": "Fire-and-forget information for the user.\n\nNotices are live events rather than session history. Agents must not rely on\na notice being received, displayed, or seen by the user.\nAgents MUST only send notices when the Client advertised\nthe `session.notices` Client capability. Otherwise, Agents may use an agent\nmessage when the information should still be surfaced to the user.\n\nSee RFD: [Session Notices](https://agentclientprotocol.com/rfds/session-notices)", "type": "object", "properties": { - "plan": { - "description": "The updated plan content.", + "severity": { + "description": "Presentation severity hint.", "allOf": [ { - "$ref": "#/$defs/PlanUpdateContent" + "$ref": "#/$defs/NoticeSeverity" } ] }, + "title": { + "description": "Required non-empty plain-text title that can stand alone.", + "type": "string", + "minLength": 1 + }, + "description": { + "description": "Optional plain-text detail or guidance.\n\nOmitted and `null` are equivalent and mean no description was supplied.", + "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/extensibility)", + "description": "Metadata scoped to this notice.\n\nOmitted and `null` are equivalent and mean no metadata was supplied.", "type": [ "object", "null" @@ -6456,23 +6488,86 @@ } }, "required": [ - "plan" + "severity", + "title" ] }, - "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.", + "CompactionId": { + "description": "Unique identifier for a context compaction within a session.", + "type": "string" + }, + "CompactionStatus": { + "description": "Lifecycle 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": "A context compaction upsert. The first notification fixes the compaction's\ntimeline position. Later updates with the same ID patch that entity in place.\nAgents MUST only send this update when the Client advertised\nthe `session.compaction` Client capability.\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 summary.", "type": "object", "properties": { - "planId": { - "description": "The plan ID to remove.", + "compactionId": { + "description": "The Agent-owned ID of this compaction, unique within the session.", "allOf": [ { - "$ref": "#/$defs/PlanId" + "$ref": "#/$defs/CompactionId" + } + ] + }, + "status": { + "description": "Current lifecycle status.", + "allOf": [ + { + "$ref": "#/$defs/CompactionStatus" } ] }, + "summary": { + "description": "Complete replacement user-displayable summary content for 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 error details for the compaction.", + "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/extensibility)", + "description": "Extensible metadata patch for this compaction.", "type": [ "object", "null" @@ -6482,35 +6577,32 @@ } }, "required": [ - "planId" + "compactionId", + "status" ] }, - "AvailableCommand": { - "description": "Information about a command.", + "CompactionSummaryChunk": { + "description": "A content block appended to a compaction's summary. A first-seen ID creates\nan in-progress compaction. Chunks append in receive order.\nAgents MUST only send this update when the Client advertised\nthe `session.compaction` Client capability.", "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": [ + "compactionId": { + "description": "ID of the compaction whose summary receives this content.", + "allOf": [ { - "$ref": "#/$defs/AvailableCommandInput" - }, + "$ref": "#/$defs/CompactionId" + } + ] + }, + "content": { + "description": "One content block to append.", + "allOf": [ { - "type": "null" + "$ref": "#/$defs/ContentBlock" } - ], - "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/extensibility)", + "description": "Metadata scoped to this chunk. Omission and `null` both mean absent.", "type": [ "object", "null" @@ -6520,34 +6612,24 @@ } }, "required": [ - "name", - "description" - ] - }, - "AvailableCommandInput": { - "description": "The input specification for a command.", - "anyOf": [ - { - "title": "unstructured", - "description": "All text that was typed after the command name is provided as input.", - "allOf": [ - { - "$ref": "#/$defs/UnstructuredCommandInput" - } - ] - } + "compactionId", + "content" ] }, - "UnstructuredCommandInput": { - "description": "All text that was typed after the command name is provided as input.", + "PromptSuggestion": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA prompt the Agent predicts the user will send next.", "type": "object", "properties": { - "hint": { - "description": "A hint to display when the input hasn't been provided yet", - "type": "string" + "prompt": { + "description": "The content of the suggested prompt.\n\nRequired and non-null. Must contain at least one content block. This is\nthe same type as the `prompt` field of `session/prompt`, and the Client\ncan send it in that field unchanged.\n\nAgents MUST only use `text` and `resource_link` content blocks, and\nother content block types that both the Agent's prompt capabilities\nand the Client's `session.promptSuggestions` capability advertise.\nAgents MUST NOT send a prompt whose only content is empty or\nwhitespace-only text.", + "type": "array", + "items": { + "$ref": "#/$defs/ContentBlock" + }, + "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -6557,24 +6639,23 @@ } }, "required": [ - "hint" + "prompt" ] }, - "AvailableCommandsUpdate": { - "description": "Available commands are ready or have changed", + "PromptSuggestionsUpdate": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nReplaces the session's current list of prompt suggestions.\n\nA prompt suggestion is a prompt the Agent predicts the user will send next.\nThe Client offers suggestions where the user writes the next prompt. The\nlist in the most recent update is the current list until the Agent sends\nanother update. A session starts with an empty list.\n\nSuggestions are not part of session history. Agents SHOULD NOT include\nthis update when they replay a session.\n\nAgents MUST only send this update when the Client advertised\nthe `session.promptSuggestions` Client capability.", "type": "object", "properties": { - "availableCommands": { - "description": "Commands the agent can execute", + "suggestions": { + "description": "The suggestions the Client can offer, ordered most likely first.\n\nRequired and non-null. An empty list withdraws the suggestions the\nClient is offering. A Client skips an entry it cannot parse and keeps\nthe rest.", "type": "array", "items": { - "$ref": "#/$defs/AvailableCommand" + "$ref": "#/$defs/PromptSuggestion" }, - "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -6584,23 +6665,31 @@ } }, "required": [ - "availableCommands" + "suggestions" ] }, - "CurrentModeUpdate": { - "description": "The current mode of the session has changed\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)", + "CursorId": { + "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 session cursor within a session.\n\nThe Agent generates it, and it is never reused for another position in the\nsession. Clients MUST NOT parse, change, or construct it.\n\nSee the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors).", + "type": "string" + }, + "CursorCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe methods that currently accept a session cursor.\n\nA malformed value falls back to no capabilities, so the Client never passes a\ncursor to a method the Agent did not advertise.\n\nSee the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors).", "type": "object", "properties": { - "currentModeId": { - "description": "The ID of the current mode", - "allOf": [ + "fork": { + "description": "Permits the Client to fork the session at this cursor with `session/fork`.\n\nOmitted and `null` are equivalent and mean unsupported. An object (including `{}`)\nmeans supported.", + "anyOf": [ { - "$ref": "#/$defs/SessionModeId" + "$ref": "#/$defs/CursorForkCapabilities" + }, + { + "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/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted and `null` are equivalent and mean no metadata.\nImplementations MUST NOT assign meaning to keys they do not recognize.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility)", "type": [ "object", "null" @@ -6608,127 +6697,269 @@ "x-deserialize-default-on-error": true, "additionalProperties": true } - }, - "required": [ - "currentModeId" - ] + } }, - "ConfigOptionUpdate": { - "description": "Session configuration options have been updated.", + "CursorForkCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapability to fork the session at a cursor with `session/fork`.\n\nSupplying `{}` advertises support. An omitted or `null` `fork` does not.", "type": "object", "properties": { - "configOptions": { - "description": "The full set of configuration options and their current values.", - "type": "array", - "items": { - "$ref": "#/$defs/SessionConfigOption" + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted and `null` are equivalent and mean no metadata.\nImplementations MUST NOT assign meaning to keys they do not recognize.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, + "CursorAnchor": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhere a session cursor is, relative to an entity the Client holds.\n\nThe anchor names the entity by its type and ID, and `position` says on which\nside of that entity the cursor is. A known `type` with a malformed payload is\nan error. It does not fall back to the unknown-type variant.\n\nSee the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors).", + "anyOf": [ + { + "description": "The cursor is next to a user message.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "user_message" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/CursorMessageAnchor" + } + ] + }, + { + "description": "The cursor is next to an agent message.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "agent_message" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/CursorMessageAnchor" + } + ] + }, + { + "description": "The cursor is next to an agent thought.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "agent_thought" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/CursorMessageAnchor" + } + ] + }, + { + "description": "The cursor is next to a session-directed message.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "session_message" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/CursorMessageAnchor" + } + ] + }, + { + "description": "The cursor is next to a tool call.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "tool_call" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/CursorToolCallAnchor" + } + ] + }, + { + "description": "The cursor is next to a compaction.", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "compaction" + } + }, + "required": [ + "type" + ], + "allOf": [ + { + "$ref": "#/$defs/CursorCompactionAnchor" + } + ] + }, + { + "title": "other", + "description": "Custom or future anchor type.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.\n\nA Client that does not recognize the type cannot place the cursor and\nMUST NOT guess a place for it.", + "type": "object", + "properties": { + "type": { + "description": "Custom or future anchor 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": "user_message" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "agent_message" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "agent_thought" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "session_message" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "tool_call" + } + }, + "required": [ + "type" + ] + }, + { + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "compaction" + } + }, + "required": [ + "type" + ] + } + ] }, - "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/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.", - "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": "ISO 8601 timestamp of last activity. Set to null to clear.", - "type": [ - "string", - "null" - ], - "x-deserialize-default-on-error": true + "CursorAnchorPosition": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nOn which side of the anchored entity a session cursor is.", + "anyOf": [ + { + "description": "The cursor is immediately before the entity. The history before the\ncursor does not include the entity.", + "type": "string", + "const": "before" }, - "_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/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" + { + "description": "The cursor is immediately after the entity. The history before the\ncursor includes the entity and nothing that follows it in the timeline.", + "type": "string", + "const": "after" }, - "currency": { - "description": "ISO 4217 currency code (e.g., \"USD\", \"EUR\").", + { + "title": "other", + "description": "Custom or future position.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Other unknown values are reserved for future ACP positions.\nA Client that does not recognize the value cannot place the cursor.", "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/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.", + "CursorMessageAnchor": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA session cursor anchor to a message. The anchor's `type` names the kind of message.", "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": [ + "messageId": { + "description": "The ID of the anchored message.", + "allOf": [ { - "$ref": "#/$defs/Cost" - }, + "$ref": "#/$defs/MessageId" + } + ] + }, + "position": { + "description": "On which side of the message the cursor is.", + "allOf": [ { - "type": "null" + "$ref": "#/$defs/CursorAnchorPosition" } - ], - "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/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted and `null` are equivalent and mean no metadata.\nImplementations MUST NOT assign meaning to keys they do not recognize.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility)", "type": [ "object", "null" @@ -6738,62 +6969,32 @@ } }, "required": [ - "used", - "size" - ] - }, - "NoticeSeverity": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSeverity hint for a session notice.", - "anyOf": [ - { - "description": "Informational notice.", - "type": "string", - "const": "info" - }, - { - "description": "Warning notice.", - "type": "string", - "const": "warning" - }, - { - "description": "Error notice.", - "type": "string", - "const": "error" - }, - { - "title": "other", - "description": "Custom or future notice severity.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Other unknown values are reserved for future ACP severities.", - "type": "string" - } + "messageId", + "position" ] }, - "Notice": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nFire-and-forget advisory information for the user.\n\nNotices are live events rather than session history. Agents must not rely on\na notice being received, displayed, or seen by the user.\nAgents MUST only send notices when the Client advertised\n[`ClientSessionCapabilities::notices`]. Otherwise, Agents may use an agent\nmessage when the information should still be surfaced to the user.\n\nSee RFD: [Session Notices](https://agentclientprotocol.com/rfds/session-notices)", + "CursorToolCallAnchor": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA session cursor anchor to a tool call.", "type": "object", "properties": { - "severity": { - "description": "Presentation severity hint.", + "toolCallId": { + "description": "The ID of the anchored tool call.", "allOf": [ { - "$ref": "#/$defs/NoticeSeverity" + "$ref": "#/$defs/ToolCallId" } ] }, - "title": { - "description": "Required non-empty plain-text title that can stand alone.", - "type": "string", - "minLength": 1 - }, - "description": { - "description": "Optional plain-text detail or guidance.\n\nOmitted and `null` are equivalent and mean no description was supplied.", - "type": [ - "string", - "null" - ], - "x-deserialize-default-on-error": true + "position": { + "description": "On which side of the tool call the cursor is.", + "allOf": [ + { + "$ref": "#/$defs/CursorAnchorPosition" + } + ] }, "_meta": { - "description": "Metadata scoped to this notice.\n\nOmitted and `null` are equivalent and mean no metadata was supplied.", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted and `null` are equivalent and mean no metadata.\nImplementations MUST NOT assign meaning to keys they do not recognize.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility)", "type": [ "object", "null" @@ -6803,86 +7004,32 @@ } }, "required": [ - "severity", - "title" - ] - }, - "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" - } + "toolCallId", + "position" ] }, - "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.\nAgents MUST only send this update when the Client advertised\n[`ClientSessionCapabilities::compaction`].\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`.", + "CursorCompactionAnchor": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA session cursor anchor to a compaction.", "type": "object", "properties": { "compactionId": { - "description": "The Agent-owned ID of this compaction, unique within the session.", + "description": "The ID of the anchored compaction.", "allOf": [ { "$ref": "#/$defs/CompactionId" } ] }, - "status": { - "description": "Current lifecycle status.", + "position": { + "description": "On which side of the compaction the cursor is.", "allOf": [ { - "$ref": "#/$defs/CompactionStatus" + "$ref": "#/$defs/CursorAnchorPosition" } ] }, - "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.", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted and `null` are equivalent and mean no metadata.\nImplementations MUST NOT assign meaning to keys they do not recognize.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility)", "type": [ "object", "null" @@ -6893,31 +7040,46 @@ }, "required": [ "compactionId", - "status" + "position" ] }, - "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. Agents MUST only send this update when\nthe Client advertised [`ClientSessionCapabilities::compaction`].", + "CursorUpdate": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA session cursor upsert. A cursor names one position in the session's timeline.\n\nThe first update for a `cursorId` MUST include `anchor`. The anchor is fixed\nafter that, and later updates change only `capabilities`.\n\nAgents MUST only send this update when the Client advertised\nthe `session.cursors` Client capability.\n\n`capabilities` and `_meta` have patch semantics: omission leaves the stored\nvalue unchanged, `null` clears it, and a concrete value replaces it.\n\nSee the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors).", "type": "object", "properties": { - "compactionId": { - "description": "ID of the compaction whose summary receives this content.", + "cursorId": { + "description": "The Agent-owned ID of this cursor, unique within the session.", "allOf": [ { - "$ref": "#/$defs/CompactionId" + "$ref": "#/$defs/CursorId" + } + ] + }, + "capabilities": { + "description": "The methods that currently accept this cursor.\n\nOmission leaves the capabilities unchanged, `null` clears them, and an object replaces\nthe whole previous value. A new cursor starts with none.", + "anyOf": [ + { + "$ref": "#/$defs/CursorCapabilities" + }, + { + "type": "null" } - ] + ], + "x-deserialize-default-on-error": true }, - "content": { - "description": "One content block to append.", - "allOf": [ + "anchor": { + "description": "Where the cursor is, relative to an entity the Client holds.\n\nRequired on the first update for a cursor. The Agent MUST NOT change it afterwards.\nA later update can omit it or repeat the same anchor. Omitted and `null` are\nequivalent and leave the stored anchor unchanged.", + "anyOf": [ { - "$ref": "#/$defs/ContentBlock" + "$ref": "#/$defs/CursorAnchor" + }, + { + "type": "null" } ] }, "_meta": { - "description": "Metadata scoped to this chunk. Omission and `null` both mean absent.", + "description": "Extensible metadata patch for this cursor.", "type": [ "object", "null" @@ -6927,16 +7089,15 @@ } }, "required": [ - "compactionId", - "content" + "cursorId" ] }, "SubagentSessionCapabilities": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nClient-initiated session mutations permitted for a specific subagent session.\n\nA mutation requires an explicit per-child capability; support for the method\non ordinary sessions does not grant support on a child.", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nClient-initiated session mutations permitted for a specific subagent session.\n\nA mutation requires an explicit per-child capability. Support for the method\non ordinary sessions does not grant support on a child.", "type": "object", "properties": { "cancel": { - "description": "Permits the client to cancel this child's current work without ending\nthe session. Omitted or `null` means unsupported; an object (including\n`{}`) means supported.", + "description": "Permits the client to cancel this child's current work without ending\nthe session. Omitted or `null` means unsupported. An object (including\n`{}`) means supported.", "anyOf": [ { "$ref": "#/$defs/SessionCancelCapabilities" @@ -6959,11 +7120,11 @@ } }, "SessionCancelCapabilities": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapability to cancel work in a subagent session without ending that session.\n\nSupplying `{}` advertises support; an omitted or `null` `cancel` does not.", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapability to cancel work in a subagent session without ending that session.\n\nSupplying `{}` advertises support. An omitted or `null` `cancel` does not.", "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -6974,7 +7135,7 @@ } }, "StateUpdate": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCurrent foreground-work state of a reusable child session.\n\nEach update is a whole-object snapshot. Idle does not terminate the child;\nthe parent can message it again, transitioning it back to running.\nBackground activity may still emit other session updates while idle.", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCurrent foreground-work state of a reusable child session.\n\nEach update is a whole-object snapshot. Idle does not terminate the child.\nThe parent can message it again, transitioning it back to running.\nBackground activity may still emit other session updates while idle.", "anyOf": [ { "description": "Foreground work is in progress.", @@ -7122,7 +7283,7 @@ "type": "object", "properties": { "_meta": { - "description": "The _meta property is reserved by ACP for additional metadata.\nImplementations MUST NOT make assumptions about values at these keys.\nOptional; omitted and `null` mean no metadata for this state snapshot.", + "description": "The _meta property is reserved by ACP for additional metadata.\nImplementations MUST NOT make assumptions about values at these keys.\nOptional. Omitted and `null` mean no metadata for this state snapshot.", "type": [ "object", "null" @@ -7132,24 +7293,30 @@ } } }, - "IdleStateUpdate": { - "description": "The child is ready to process another prompt.", + "ErrorStopReason": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nDetails of a failure that ended a child's foreground work.", "type": "object", "properties": { - "stopReason": { - "description": "Reason foreground work stopped. Optional; omitted or `null` means not reported.", + "error": { + "description": "The failure, as a JSON-RPC error object.\n\nOptional. Omitted or `null` both mean the agent is not reporting failure details.\nAgents SHOULD include it.", "anyOf": [ { - "$ref": "#/$defs/StopReason" + "$ref": "#/$defs/Error" }, { "type": "null" } ], "x-deserialize-default-on-error": true - }, + } + } + }, + "IdleStateUpdate": { + "description": "The child is ready to process another prompt.\n\nAn omitted, `null`, or malformed `stopReason` means not reported.", + "type": "object", + "properties": { "usage": { - "description": "**UNSTABLE** Token usage for completed foreground work.\n\nOptional; omitted or `null` means not reported.", + "description": "**UNSTABLE** Token usage for completed foreground work.\n\nOptional. Omitted or `null` means not reported.", "anyOf": [ { "$ref": "#/$defs/Usage" @@ -7161,22 +7328,216 @@ "x-deserialize-default-on-error": true }, "_meta": { - "description": "The _meta property is reserved by ACP for additional metadata.\nImplementations MUST NOT make assumptions about values at these keys.\nOptional; omitted and `null` mean no metadata for this state snapshot.", + "description": "The _meta property is reserved by ACP for additional metadata.\nImplementations MUST NOT make assumptions about values at these keys.\nOptional. Omitted and `null` mean no metadata for this state snapshot.", "type": [ "object", "null" ], "x-deserialize-default-on-error": true, "additionalProperties": true + }, + "stopReason": { + "description": "Why foreground work stopped. The value selects one of this type's variants, which may add fields of their own.\n\nOptional. Omitted or `null` both mean the agent is not reporting a stop reason; a malformed value is treated the same way.\n\nSee protocol docs: [Work state](https://agentclientprotocol.com/protocol/v1/draft/subagents#work-state)", + "type": [ + "string", + "null" + ], + "x-deserialize-default-on-error": true } - } + }, + "anyOf": [ + { + "description": "The work ended successfully.", + "type": "object", + "properties": { + "stopReason": { + "type": "string", + "const": "end_turn" + } + }, + "required": [ + "stopReason" + ] + }, + { + "description": "The work ended because the agent reached the maximum number of tokens.", + "type": "object", + "properties": { + "stopReason": { + "type": "string", + "const": "max_tokens" + } + }, + "required": [ + "stopReason" + ] + }, + { + "description": "The work ended because the agent reached the maximum number of allowed\nagent requests.", + "type": "object", + "properties": { + "stopReason": { + "type": "string", + "const": "max_turn_requests" + } + }, + "required": [ + "stopReason" + ] + }, + { + "description": "The work ended because the agent refused to continue.", + "type": "object", + "properties": { + "stopReason": { + "type": "string", + "const": "refusal" + } + }, + "required": [ + "stopReason" + ] + }, + { + "description": "The work was cancelled.", + "type": "object", + "properties": { + "stopReason": { + "type": "string", + "const": "cancelled" + } + }, + "required": [ + "stopReason" + ] + }, + { + "description": "The work ended because something failed.", + "type": "object", + "properties": { + "stopReason": { + "type": "string", + "const": "error" + } + }, + "required": [ + "stopReason" + ], + "allOf": [ + { + "$ref": "#/$defs/ErrorStopReason" + } + ] + }, + { + "title": "other", + "description": "Custom or future stop reason.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Other unknown values are reserved for future ACP variants.", + "type": "object", + "properties": { + "stopReason": { + "description": "Unrecognized stop reason.", + "type": "string" + } + }, + "required": [ + "stopReason" + ], + "not": { + "anyOf": [ + { + "type": "object", + "properties": { + "stopReason": { + "type": "string", + "const": "end_turn" + } + }, + "required": [ + "stopReason" + ] + }, + { + "type": "object", + "properties": { + "stopReason": { + "type": "string", + "const": "max_tokens" + } + }, + "required": [ + "stopReason" + ] + }, + { + "type": "object", + "properties": { + "stopReason": { + "type": "string", + "const": "max_turn_requests" + } + }, + "required": [ + "stopReason" + ] + }, + { + "type": "object", + "properties": { + "stopReason": { + "type": "string", + "const": "refusal" + } + }, + "required": [ + "stopReason" + ] + }, + { + "type": "object", + "properties": { + "stopReason": { + "type": "string", + "const": "cancelled" + } + }, + "required": [ + "stopReason" + ] + }, + { + "type": "object", + "properties": { + "stopReason": { + "type": "string", + "const": "error" + } + }, + "required": [ + "stopReason" + ] + } + ] + }, + "additionalProperties": true + }, + { + "title": "none", + "description": "No stop reason: `stopReason` is omitted or `null`.", + "type": "object", + "properties": { + "stopReason": { + "type": "null" + } + } + } + ] }, "RequiresActionStateUpdate": { "description": "Foreground work is blocked on user action.", "type": "object", "properties": { "_meta": { - "description": "The _meta property is reserved by ACP for additional metadata.\nImplementations MUST NOT make assumptions about values at these keys.\nOptional; omitted and `null` mean no metadata for this state snapshot.", + "description": "The _meta property is reserved by ACP for additional metadata.\nImplementations MUST NOT make assumptions about values at these keys.\nOptional. Omitted and `null` mean no metadata for this state snapshot.", "type": [ "object", "null" @@ -7187,11 +7548,11 @@ } }, "UnknownStateUpdate": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe Agent cannot currently determine foreground activity.\n\nReport this when activity becomes unobservable, not merely because the child\nhas been quiet. The Client MUST stop presenting the previous state as confirmed\ncurrent activity, but may retain it as last known. A later state replaces this\nsnapshot normally.\n\nThis is not a task outcome or session closure. It does not cancel work, resolve\npending requests, or revoke capabilities; capabilities are updated separately.", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe Agent cannot currently determine foreground activity.\n\nReport this when activity becomes unobservable, not merely because the child\nhas been quiet. The Client MUST stop presenting the previous state as confirmed\ncurrent activity, but may retain it as last known. A later state replaces this\nsnapshot normally.\n\nThis is not a task outcome or session closure. It does not cancel work, resolve\npending requests, or revoke capabilities. If a control is no longer available,\nthe Agent updates the capabilities explicitly. Unfinished tool calls and\nterminals stay as last reported. The Agent does not invent a final status\nfor them, and Clients do not present them as confirmed live activity.", "type": "object", "properties": { "_meta": { - "description": "The _meta property is reserved by ACP for additional metadata.\nImplementations MUST NOT make assumptions about values at these keys.\nOptional; omitted and `null` mean no metadata for this state snapshot.", + "description": "The _meta property is reserved by ACP for additional metadata.\nImplementations MUST NOT make assumptions about values at these keys.\nOptional. Omitted and `null` mean no metadata for this state snapshot.", "type": [ "object", "null" @@ -7202,7 +7563,7 @@ } }, "SubagentUpdate": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nNotification that the enclosing parent session created and owns a child session.\n\nLater updates modify the existing association's metadata, not its ownership.\n\nSent on the immediate parent session. The first update for an unknown\n[`SubagentUpdate::session_id`] announces the child and MUST be sent\nbefore any live child traffic or live message naming the child as sender\nor recipient. Parents may message and reuse an announced child across\nmultiple operations.\nChild events are delivered automatically on the same connection; no child\nload, resume, or subscription is needed.\n\nOnly the subagent session ID is required. Omitted patch fields keep their\nprevious values; `null` clears them. Clearing capabilities disables child\nmutations. Clearing state leaves current activity unset/unconfirmed: it does\nnot imply idle, stop work, or create an `unknown` state snapshot. A concrete\nstate replaces the entire previous state object, not the session.\nThe title and description provide the parent's display metadata for the\nchild. They do not replace the content of individual messages or operations.", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nNotification that the enclosing parent session created and owns a child session.\n\nLater updates modify the existing association's metadata, not its ownership.\n\nSent on the immediate parent session. The first update for an unknown\n`sessionId` announces the child and MUST be sent\nbefore any live child traffic or live message naming the child as sender\nor recipient. Parents may message and reuse an announced child across\nmultiple operations.\nChild events are delivered automatically on the same connection. No child\nload, resume, or subscription is needed.\n\nOnly the subagent session ID is required. Omitted patch fields keep their\nprevious values. `null` clears them. Clearing capabilities disables child\nmutations. Clearing state leaves current activity unset/unconfirmed: it does\nnot imply idle, stop work, or create an `unknown` state snapshot. A concrete\nstate replaces the entire previous state object, not the session.\nThe title and description provide the parent's display metadata for the\nchild. They do not replace the content of individual messages or operations.\n`cwd` and `additionalDirectories` report where the Agent placed the child.\nWhile unset, each inherits the immediate parent's effective value.", "type": "object", "properties": { "sessionId": { @@ -7214,7 +7575,7 @@ ] }, "title": { - "description": "The parent's human-readable display title for this child. It need not be unique.\n\nOmitted means unchanged; `null` clears it. If unset, the Client chooses\na fallback presentation.", + "description": "The parent's human-readable display title for this child. It need not be unique.\n\nOmitted means unchanged. `null` clears it. If unset, the Client chooses\na fallback presentation.", "type": [ "string", "null" @@ -7222,7 +7583,7 @@ "x-deserialize-default-on-error": true }, "description": { - "description": "The parent's human-readable description of the child's role or purpose.\n\nOmitted means unchanged; `null` clears it. If unset, the Client chooses\na fallback presentation. This is current display metadata, not the\nhistory of instructions sent to the child.", + "description": "The parent's human-readable description of the child's role or purpose.\n\nOmitted means unchanged. `null` clears it. If unset, the Client chooses\na fallback presentation. This is current display metadata, not the\nhistory of instructions sent to the child.", "type": [ "string", "null" @@ -7230,7 +7591,7 @@ "x-deserialize-default-on-error": true }, "capabilities": { - "description": "Client-initiated session mutations permitted for this subagent session.\n\nOmitted means unchanged; `null` clears the capability set and disables\nchild mutations. If never supplied, no session mutations are permitted.\nRead-only operations retain their normal protocol semantics and capability\nrequirements. A concrete object replaces the whole capability set.", + "description": "Client-initiated session mutations permitted for this subagent session.\n\nOmitted means unchanged. `null` clears the capability set and disables\nchild mutations. If never supplied, no session mutations are permitted.\nRead-only operations retain their normal protocol semantics and capability\nrequirements. A concrete object replaces the whole capability set.", "anyOf": [ { "$ref": "#/$defs/SubagentSessionCapabilities" @@ -7242,7 +7603,7 @@ "x-deserialize-default-on-error": true }, "state": { - "description": "Current state snapshot for the child session.\n\nOmitted means unchanged; `null` clears the current activity without\nasserting idle or sending an `unknown` snapshot. A concrete state\nreplaces the previous state object wholesale. If never supplied, the\ncurrent activity is unset/unconfirmed.", + "description": "Current state snapshot for the child session.\n\nOmitted means unchanged. `null` clears the current activity without\nasserting idle or sending an `unknown` snapshot. A concrete state\nreplaces the previous state object wholesale. If never supplied, the\ncurrent activity is unset/unconfirmed.", "anyOf": [ { "$ref": "#/$defs/StateUpdate" @@ -7253,8 +7614,25 @@ ], "x-deserialize-default-on-error": true }, + "cwd": { + "description": "The child's working directory. Must be an absolute path.\n\nOptional and nullable. Omitted means unchanged. `null` clears the\nreported value. While unset, the child inherits its immediate parent's\neffective working directory. Clients use this value for the child's\nroot set and as the default terminal working directory.", + "type": [ + "string", + "null" + ] + }, + "additionalDirectories": { + "description": "Additional workspace roots for the child. Each path must be absolute.\n\nOptional and nullable. Omitted means unchanged. `null` clears the\nreported value. While unset, the child inherits its immediate parent's\neffective additional directories, independently of `cwd`. A concrete\narray replaces the whole list. `[]` reports no additional directories.\nClients use these values for the child's root set.", + "type": [ + "array", + "null" + ], + "items": { + "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/extensibility)\nOmitted means unchanged; `null` removes the metadata.", + "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/v1/draft/extensibility)\nOmitted means unchanged. `null` removes the metadata.", "type": [ "object", "null" @@ -7280,7 +7658,7 @@ ] }, "senderSessionId": { - "description": "Optional sending session identity; omission or `null` retains a known value.", + "description": "The sending session.\n\nOmitted leaves the stored value unchanged. `null` clears it. A value replaces it.", "anyOf": [ { "$ref": "#/$defs/SessionId" @@ -7292,7 +7670,7 @@ "x-deserialize-default-on-error": true }, "recipientSessionId": { - "description": "Optional receiving session identity; omission or `null` retains a known value.", + "description": "The receiving session.\n\nOmitted leaves the stored value unchanged. `null` clears it. A value replaces it.", "anyOf": [ { "$ref": "#/$defs/SessionId" @@ -7303,8 +7681,32 @@ ], "x-deserialize-default-on-error": true }, + "senderMessageId": { + "description": "On an incoming view, the `messageId` of the same message's outgoing view in the\nsender's transcript.\n\nOmitted leaves the stored value unchanged. `null` clears it. A value replaces it. It can arrive\nafter the message starts streaming.", + "anyOf": [ + { + "$ref": "#/$defs/MessageId" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "recipientMessageId": { + "description": "On an outgoing view, the `messageId` of the same message's incoming view in the\nrecipient's transcript.\n\nOmitted leaves the stored value unchanged. `null` clears it. A value replaces it. It can arrive\nafter the message starts streaming.", + "anyOf": [ + { + "$ref": "#/$defs/MessageId" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, "content": { - "description": "Omitted leaves content unchanged; `null` or `[]` clears it.\nA non-empty array replaces all content.", + "description": "Omitted leaves content unchanged. `null` or `[]` clears it.\nA non-empty array replaces all content.", "type": [ "array", "null" @@ -7316,7 +7718,7 @@ "x-deserialize-skip-invalid-items": true }, "_meta": { - "description": "Omitted leaves metadata unchanged; `null` removes it.\n\nImplementations MUST NOT make assumptions about values in `_meta`.", + "description": "Omitted leaves metadata unchanged. `null` removes it.\n\nImplementations MUST NOT make assumptions about values in `_meta`.", "type": [ "object", "null" @@ -7330,7 +7732,7 @@ ] }, "SessionMessageChunk": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA streamed content block of an inter-session message.", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA streamed content block of an inter-session message.\n\nA chunk carries only content. The message's participants and references come from\n`session_message` upserts, which can arrive before, between, or after its chunks.", "type": "object", "properties": { "messageId": { @@ -7341,40 +7743,43 @@ } ] }, - "senderSessionId": { - "description": "Optional sending session identity; omission or `null` retains a known value.", - "anyOf": [ - { - "$ref": "#/$defs/SessionId" - }, + "content": { + "description": "A single content block appended to the message.", + "allOf": [ { - "type": "null" + "$ref": "#/$defs/ContentBlock" } - ], - "x-deserialize-default-on-error": true + ] }, - "recipientSessionId": { - "description": "Optional receiving session identity; omission or `null` retains a known value.", - "anyOf": [ - { - "$ref": "#/$defs/SessionId" - }, - { - "type": "null" - } + "_meta": { + "description": "Optional and nullable chunk-scoped metadata. Omitted or `null` means none.\n\nImplementations MUST NOT make assumptions about values in `_meta`.", + "type": [ + "object", + "null" ], - "x-deserialize-default-on-error": true - }, - "content": { - "description": "A single content block appended to the message.", + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "messageId", + "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/ContentBlock" + "$ref": "#/$defs/ElicitationId" } ] }, "_meta": { - "description": "Optional and nullable chunk-scoped metadata; omitted or `null` means none.\n\nImplementations MUST NOT make assumptions about values in `_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/v1/draft/extensibility)", "type": [ "object", "null" @@ -7384,24 +7789,34 @@ } }, "required": [ - "messageId", - "content" - ] + "elicitationId" + ], + "x-side": "client", + "x-method": "elicitation/complete" }, - "CompleteElicitationNotification": { - "description": "Notification sent by the agent when a URL-based elicitation is complete.", + "AuthStatusUpdateNotification": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nNotification sent by the agent when its authentication status changes.\n\nCarries the same fields as the `auth/status` response. Agents that advertise the\n`auth.status` capability MAY send it at any time after `initialize`, and SHOULD only\nsend it when the reported status differs from the last one sent on the connection.", "type": "object", "properties": { - "elicitationId": { - "description": "The ID of the elicitation that completed.", + "state": { + "description": "Whether the agent can start sessions without the user signing in first.\n\nClients use this field to decide whether sign-in is needed. Clients MUST treat\nvalues they do not recognize as `unknown`.", "allOf": [ { - "$ref": "#/$defs/ElicitationId" + "$ref": "#/$defs/AuthState" } ] }, + "accounts": { + "description": "The accounts the agent has configured, for display.\n\nOptional. Omitted and empty are equivalent and mean no accounts are reported.\nAgents that hold credentials for several providers or accounts SHOULD list each\nof them and mark the ones in effect with `active`.", + "type": "array", + "items": { + "$ref": "#/$defs/AuthAccount" + }, + "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -7411,13 +7826,13 @@ } }, "required": [ - "elicitationId" + "state" ], "x-side": "client", - "x-method": "elicitation/complete" + "x-method": "auth/status_update" }, "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/extensibility)" + "description": "Allows either side 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/v1/draft/extensibility)" }, "ClientRequest": { "description": "A JSON-RPC request object.", @@ -7443,7 +7858,7 @@ "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/initialization)", + "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/v1/draft/initialization)", "allOf": [ { "$ref": "#/$defs/InitializeRequest" @@ -7452,7 +7867,7 @@ }, { "title": "AuthenticateRequest", - "description": "Authenticates the client using the specified authentication method.\n\nCalled when the agent requires authentication before allowing session creation.\nThe client provides an authentication method ID that was advertised during\ninitialization and whose type defines the `authenticate` flow.\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/initialization)", + "description": "Authenticates the client using the specified authentication method.\n\nCalled when the agent requires authentication before allowing session creation.\nThe client provides an authentication method ID that was advertised during\ninitialization and whose type defines the `authenticate` flow.\n\nAfter successful authentication, the client can proceed to create sessions with\n`session/new` without receiving an `auth_required` (`-32000`) error.\n\nSee protocol docs: [Initialization](https://agentclientprotocol.com/protocol/v1/draft/initialization)", "allOf": [ { "$ref": "#/$defs/AuthenticateRequest" @@ -7495,9 +7910,18 @@ } ] }, + { + "title": "AuthStatusRequest", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nQueries the agent's current authentication state.\n\nThis method is only available if the agent advertises the `auth.status` capability.\nIt MUST NOT change any agent state, and agents MUST NOT reject it with `auth_required`.", + "allOf": [ + { + "$ref": "#/$defs/AuthStatusRequest" + } + ] + }, { "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/session-setup)", + "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` (`-32000`) error if the agent requires authentication.\n\nSee protocol docs: [Session Setup](https://agentclientprotocol.com/protocol/v1/draft/session-setup)", "allOf": [ { "$ref": "#/$defs/NewSessionRequest" @@ -7506,7 +7930,7 @@ }, { "title": "LoadSessionRequest", - "description": "Loads an existing session to resume a previous conversation.\n\nThis method is only available if the agent advertises the `loadSession` capability.\n\nThe agent should:\n- Restore the session context and conversation history\n- Connect to the specified MCP servers\n- Stream the entire conversation history back to the client via notifications\n\nSee protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/session-setup#loading-sessions)", + "description": "Loads an existing session to resume a previous conversation.\n\nThis method is only available if the agent advertises the `loadSession` capability.\n\nThe agent should:\n- Restore the session context and conversation history\n- Connect to the specified MCP servers\n- Stream the entire conversation history back to the client via notifications\n\nSee protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/v1/draft/session-setup#loading-sessions)", "allOf": [ { "$ref": "#/$defs/LoadSessionRequest" @@ -7533,7 +7957,7 @@ }, { "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.", + "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.\n\nAs with `session/new`, the forked session is active once the agent responds,\nset up with the request's `cwd`, `additionalDirectories`, and `mcpServers`.\nThe client can prompt it without calling `session/load` or `session/resume` first.", "allOf": [ { "$ref": "#/$defs/ForkSessionRequest" @@ -7541,80 +7965,98 @@ ] }, { - "title": "ResumeSessionRequest", - "description": "Resumes an existing session without returning previous messages.\n\nThis method is only available if the agent advertises the `sessionCapabilities.resume` capability.\n\nThe agent should resume the session context, allowing the conversation to continue\nwithout replaying the message history (unlike `session/load`).", + "title": "ArchiveSessionRequest", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nArchives a session, hiding it from default `session/list` results.\n\nThis method is only available if the agent advertises the `sessionCapabilities.archive` capability.", "allOf": [ { - "$ref": "#/$defs/ResumeSessionRequest" + "$ref": "#/$defs/ArchiveSessionRequest" } ] }, { - "title": "CloseSessionRequest", - "description": "Closes an active session and frees up any resources associated with it.\n\nThis method is only available if the agent advertises the `sessionCapabilities.close` capability.\n\nThe agent must cancel any ongoing work (as if `session/cancel` was called)\nand then free up any resources associated with the session.", + "title": "UnarchiveSessionRequest", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnarchives a session, returning it to default `session/list` results.\n\nThis method is only available if the agent advertises the `sessionCapabilities.archive` capability.", "allOf": [ { - "$ref": "#/$defs/CloseSessionRequest" + "$ref": "#/$defs/UnarchiveSessionRequest" } ] }, { - "title": "SetSessionModeRequest", - "description": "Sets the current mode for a session.\n\nAllows switching between different agent modes (e.g., \"ask\", \"architect\", \"code\")\nthat affect system prompts, tool availability, and permission behaviors.\n\nThe mode must be one of the modes advertised in `availableModes` during session\ncreation or loading. Agents may also change modes autonomously and notify the\nclient via `current_mode_update` notifications.\n\nThis method can be called at any time during a session, whether the Agent is\nidle or actively generating a response.\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)", + "title": "SessionStatusRequest", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nChecks whether the Agent has a session in memory, without changing it.\n\nThis method is only available if the agent advertises the `sessionCapabilities.status` capability.", "allOf": [ { - "$ref": "#/$defs/SetSessionModeRequest" + "$ref": "#/$defs/SessionStatusRequest" } ] }, { - "title": "SetSessionConfigOptionRequest", - "description": "Sets the current value for a session configuration option.", + "title": "SessionOptionsRequest", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nReturns the config options a session would start with, without creating or resuming a session.\n\nThis method is only available if the agent advertises the `sessionCapabilities.options` capability.", "allOf": [ { - "$ref": "#/$defs/SetSessionConfigOptionRequest" + "$ref": "#/$defs/SessionOptionsRequest" } ] }, { - "title": "PromptRequest", - "description": "Processes a user prompt within a session.\n\nThis method handles the whole lifecycle of a prompt:\n- Receives user messages with optional context (files, images, etc.)\n- Processes the prompt using language models\n- Reports language model content and tool calls to the Clients\n- Requests permission to run tools\n- Executes any requested tool calls\n- Returns when the turn is complete with a stop reason\n\nSee protocol docs: [Prompt Turn](https://agentclientprotocol.com/protocol/prompt-turn)", + "title": "SetSessionTitleRequest", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSets the title of a session.\n\nThis method is only available if the agent advertises the `sessionCapabilities.title` capability.\n\nThe session does not need to be active on the connection. The agent stores the\ntitle and returns the stored title, which may be normalized.", "allOf": [ { - "$ref": "#/$defs/PromptRequest" + "$ref": "#/$defs/SetSessionTitleRequest" + } + ] + }, + { + "title": "ResumeSessionRequest", + "description": "Resumes an existing session without returning previous messages.\n\nThis method is only available if the agent advertises the `sessionCapabilities.resume` capability.\n\nThe agent should resume the session context, allowing the conversation to continue\nwithout replaying the message history (unlike `session/load`).", + "allOf": [ + { + "$ref": "#/$defs/ResumeSessionRequest" + } + ] + }, + { + "title": "CloseSessionRequest", + "description": "Closes an active session and frees up any resources associated with it.\n\nThis method is only available if the agent advertises the `sessionCapabilities.close` capability.\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": "StartNesRequest", - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nStarts an NES session.", + "title": "SetSessionModeRequest", + "description": "Sets the current mode for a session.\n\nAllows switching between different agent modes (e.g., \"ask\", \"architect\", \"code\")\nthat affect system prompts, tool availability, and permission behaviors.\n\nThe mode must be one of the modes advertised in `availableModes` during session\ncreation or loading. Agents may also change modes autonomously and notify the\nclient via `current_mode_update` notifications.\n\nThis method can be called at any time during a session, whether the Agent is\nidle or actively generating a response.\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/draft/session-modes)", "allOf": [ { - "$ref": "#/$defs/StartNesRequest" + "$ref": "#/$defs/SetSessionModeRequest" } ] }, { - "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.", + "title": "SetSessionConfigOptionRequest", + "description": "Sets the current value for a session configuration option.", "allOf": [ { - "$ref": "#/$defs/SuggestNesRequest" + "$ref": "#/$defs/SetSessionConfigOptionRequest" } ] }, { - "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.", + "title": "PromptRequest", + "description": "Processes a user prompt within a session.\n\nThis method handles the whole lifecycle of a prompt:\n- Receives user messages with optional context (files, images, etc.)\n- Processes the prompt using language models\n- Reports language model content and tool calls to the Clients\n- Requests permission to run tools\n- Executes any requested tool calls\n- Returns when the turn is complete with a stop reason\n\nSee protocol docs: [Prompt Turn](https://agentclientprotocol.com/protocol/v1/draft/prompt-turn)", "allOf": [ { - "$ref": "#/$defs/CloseNesRequest" + "$ref": "#/$defs/PromptRequest" } ] }, { "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/extensibility)", + "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/v1/draft/extensibility)", "allOf": [ { "$ref": "#/$defs/ExtRequest" @@ -7636,7 +8078,7 @@ "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/initialization)", + "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/v1/draft/initialization)", "type": "object", "properties": { "protocolVersion": { @@ -7679,7 +8121,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -7695,7 +8137,7 @@ "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/initialization#client-capabilities)", + "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/v1/draft/initialization#client-capabilities)", "type": "object", "properties": { "fs": { @@ -7777,29 +8219,8 @@ ], "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -7810,7 +8231,7 @@ } }, "FileSystemCapabilities": { - "description": "File system capabilities that a client may support.\n\nSee protocol docs: [FileSystem](https://agentclientprotocol.com/protocol/initialization#filesystem)", + "description": "File system capabilities that a client may support.\n\nSee protocol docs: [FileSystem](https://agentclientprotocol.com/protocol/v1/draft/initialization#filesystem)", "type": "object", "properties": { "readTextFile": { @@ -7826,7 +8247,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -7841,7 +8262,7 @@ "type": "object", "properties": { "compaction": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSupport for ID-addressed context compaction updates. Omitted or `null`\nmeans unsupported; `{}` advertises the complete compaction contract.", + "description": "Support for ID-addressed context compaction updates. Omitted or `null`\nmeans unsupported. `{}` advertises the complete compaction contract.", "anyOf": [ { "$ref": "#/$defs/CompactionCapabilities" @@ -7865,7 +8286,7 @@ "x-deserialize-default-on-error": true }, "notices": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSupport for live advisory `notice` session updates.\n\nOptional. Omitted or `null` both mean the client does not advertise support.\nSupplying `{}` means the client can present notices to the user.", + "description": "Support for live user-facing `notice` session updates.\n\nOptional. Omitted or `null` both mean the client does not advertise support.\nSupplying `{}` means the client can present notices to the user.", "anyOf": [ { "$ref": "#/$defs/NoticeCapabilities" @@ -7876,8 +8297,32 @@ ], "x-deserialize-default-on-error": true }, + "promptSuggestions": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSupport for `prompt_suggestions_update` session updates.\n\nOptional. Omitted or `null` both mean the client does not advertise support.\nSupplying `{}` means the client can offer prompt suggestions made of\n`text` and `resource_link` content blocks.", + "anyOf": [ + { + "$ref": "#/$defs/PromptSuggestionsCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "cursors": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSupport for `cursor_update` session updates.\n\nOptional. Omitted or `null` both mean the client does not advertise support.\nSupplying `{}` means the client handles `cursor_update`.", + "anyOf": [ + { + "$ref": "#/$defs/SessionCursorsCapabilities" + }, + { + "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -7888,7 +8333,7 @@ } }, "CompactionCapabilities": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nClient support for ID-addressed context compaction updates.", + "description": "Client support for ID-addressed context compaction updates.", "type": "object" }, "SessionConfigOptionsCapabilities": { @@ -7908,7 +8353,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -7923,7 +8368,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -7934,15 +8379,51 @@ } }, "NoticeCapabilities": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nClient support for presenting live advisory notices to the user.", + "description": "Client support for presenting live notices to the user.", "type": "object" }, - "SubagentCapabilities": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapability marker for exposing reusable child sessions as restricted ACP sessions.\n\nSupplying `{}` advertises support for child association and state updates,\nsession-directed messages, and restricted-session semantics. The client\nmust advertise this capability before the agent sends subagent updates or\nsession-directed messages.", + "PromptSuggestionsCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nClient support for `prompt_suggestions_update` session updates.\n\nSupplying `{}` means the client can offer prompt suggestions made of `text`\nand `resource_link` content blocks. The client opts in to other content\nblock types with the fields below. They have the same names as the agent's\nprompt capabilities.", "type": "object", "properties": { + "image": { + "description": "Whether prompt suggestions may include `image` content blocks.\n\nOptional. Omitted or `null` both mean the client does not advertise support.\nSupplying `{}` means the client can offer suggestions that include images.", + "anyOf": [ + { + "$ref": "#/$defs/PromptSuggestionsImageCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "audio": { + "description": "Whether prompt suggestions may include `audio` content blocks.\n\nOptional. Omitted or `null` both mean the client does not advertise support.\nSupplying `{}` means the client can offer suggestions that include audio.", + "anyOf": [ + { + "$ref": "#/$defs/PromptSuggestionsAudioCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, + "embeddedContext": { + "description": "Whether prompt suggestions may include `resource` content blocks.\n\nOptional. Omitted or `null` both mean the client does not advertise support.\nSupplying `{}` means the client can offer suggestions that include\nembedded resources.", + "anyOf": [ + { + "$ref": "#/$defs/PromptSuggestionsEmbeddedContextCapabilities" + }, + { + "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.", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -7952,12 +8433,12 @@ } } }, - "PlanCapabilities": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapabilities for receiving `plan_update` and `plan_removed` session updates.", + "PromptSuggestionsImageCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapabilities for image content in prompt suggestions.\n\nSupplying `{}` means the client can offer suggestions that include images.", "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -7967,18 +8448,12 @@ } } }, - "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.", + "PromptSuggestionsAudioCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapabilities for audio content in prompt suggestions.\n\nSupplying `{}` means the client can offer suggestions that include audio.", "type": "object", "properties": { - "terminal": { - "description": "Whether the client supports `terminal` authentication methods.\n\nThe client should set this to `true` only when it can reproduce the\nconfigured agent invocation in an interactive terminal. When `true`, the\nagent may include `terminal` entries in its authentication methods.", - "type": "boolean", - "default": false, - "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -7988,36 +8463,12 @@ } } }, - "ElicitationCapabilities": { - "description": "Elicitation capabilities supported by the client.", + "PromptSuggestionsEmbeddedContextCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapabilities for embedded resources in prompt suggestions.\n\nSupplying `{}` means the client can offer suggestions that include\n`resource` content blocks.", "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -8027,12 +8478,16 @@ } } }, - "ElicitationFormCapabilities": { - "description": "Form-based elicitation capabilities.\n\nSupplying `{}` means the client supports form-based elicitation.", + "SessionCursorsCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nClient support for `cursor_update` session updates.\n\nSee the [Session Cursors RFD](https://agentclientprotocol.com/rfds/session-cursors).", + "type": "object" + }, + "SubagentCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapability marker for exposing reusable child sessions as restricted ACP sessions.\n\nSupplying `{}` advertises support for child association and state updates,\nsession-directed messages, and restricted-session semantics. The client\nmust advertise this capability before the agent sends subagent updates or\nsession-directed messages.", "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/extensibility)", + "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.", "type": [ "object", "null" @@ -8042,12 +8497,12 @@ } } }, - "ElicitationUrlCapabilities": { - "description": "URL-based elicitation capabilities.\n\nSupplying `{}` means the client supports URL-based elicitation.", + "PlanCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapabilities for receiving `plan_update` and `plan_removed` session updates.", "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -8057,27 +8512,36 @@ } } }, - "ClientNesCapabilities": { - "description": "NES capabilities advertised by the client during initialization.", + "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": { - "jump": { - "description": "Whether the client supports the `jump` suggestion kind.", - "anyOf": [ - { - "$ref": "#/$defs/NesJumpCapabilities" - }, - { - "type": "null" - } - ], + "terminal": { + "description": "Whether the client supports `terminal` authentication methods.\n\nThe client should set this to `true` only when it can reproduce the\nconfigured agent invocation in an interactive terminal. When `true`, the\nagent may include `terminal` entries in its authentication methods.", + "type": "boolean", + "default": false, "x-deserialize-default-on-error": true }, - "rename": { - "description": "Whether the client supports the `rename` suggestion kind.", + "_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/v1/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/NesRenameCapabilities" + "$ref": "#/$defs/ElicitationFormCapabilities" }, { "type": "null" @@ -8085,11 +8549,11 @@ ], "x-deserialize-default-on-error": true }, - "searchAndReplace": { - "description": "Whether the client supports the `searchAndReplace` suggestion kind.", + "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/NesSearchAndReplaceCapabilities" + "$ref": "#/$defs/ElicitationUrlCapabilities" }, { "type": "null" @@ -8098,22 +8562,7 @@ "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/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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -8123,12 +8572,12 @@ } } }, - "NesRenameCapabilities": { - "description": "Marker for rename suggestion support.", + "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\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -8138,12 +8587,12 @@ } } }, - "NesSearchAndReplaceCapabilities": { - "description": "Marker for search and replace suggestion support.", + "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\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -8166,7 +8615,7 @@ ] }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -8186,7 +8635,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -8230,7 +8679,7 @@ } }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -8260,7 +8709,7 @@ ] }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -8280,7 +8729,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -8292,8 +8741,25 @@ "x-side": "agent", "x-method": "logout" }, + "AuthStatusRequest": { + "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 the `auth/status` method.\n\nQueries the agent's current authentication state without changing it.\n\nAgents MUST NOT reject it with `auth_required` (`-32000`), since Clients call it to learn\nwhether authentication is required.", + "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/v1/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "x-side": "agent", + "x-method": "auth/status" + }, "NewSessionRequest": { - "description": "Request parameters for creating a new session.\n\nSee protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/session-setup#creating-a-session)", + "description": "Request parameters for creating a new session.\n\nSee protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/v1/draft/session-setup#creating-a-session)", "type": "object", "properties": { "cwd": { @@ -8306,8 +8772,7 @@ "items": { "type": "string" }, - "x-deserialize-default-on-error": true, - "x-deserialize-skip-invalid-items": true + "x-deserialize-default-on-null": true }, "mcpServers": { "description": "List of MCP (Model Context Protocol) servers the agent should connect to.", @@ -8315,11 +8780,29 @@ "items": { "$ref": "#/$defs/McpServer" }, - "x-deserialize-default-on-error": true, - "x-deserialize-skip-invalid-items": true + "x-deserialize-default-on-null": true + }, + "systemPrompt": { + "description": "System-level instructions for the new session.\n\nOptional. Omitted and `null` are equivalent and mean the Agent uses its\nown default instructions. Clients MUST only send this when the Agent\nadvertises `sessionCapabilities.systemPrompt`.", + "anyOf": [ + { + "$ref": "#/$defs/SystemPrompt" + }, + { + "type": "null" + } + ] + }, + "configOptions": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial values for the session's config options.\n\nOptional. Omitted and `null` are equivalent to an empty list. Clients MUST only send\nthis when the Agent advertises `sessionCapabilities.options`.\n\nThe Agent applies the entries in list order, as if the Client had called\n`session/set_config_option` for each entry after the session was set up. Malformed\nentries and duplicate `configId` values fail the request with `-32602`. The Agent MUST\nignore an entry whose `configId` is unknown, whose `type` does not match the option,\nor whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually\nhas. The Agent SHOULD NOT send `config_option_update` notifications for these entries,\nand SHOULD NOT send other `session/update` notifications caused by applying them\nbefore it responds.", + "type": "array", + "items": { + "$ref": "#/$defs/InitialSessionConfigOption" + }, + "x-deserialize-default-on-null": 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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -8336,7 +8819,7 @@ "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/session-setup#mcp-servers)", + "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/v1/draft/session-setup#mcp-servers)", "anyOf": [ { "description": "HTTP transport configuration\n\nOnly available when the Agent capabilities indicate `mcp_capabilities.http` is `true`.", @@ -8416,7 +8899,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -8447,10 +8930,11 @@ "type": "array", "items": { "$ref": "#/$defs/HttpHeader" - } + }, + "x-deserialize-default-on-null": 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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -8482,10 +8966,11 @@ "type": "array", "items": { "$ref": "#/$defs/HttpHeader" - } + }, + "x-deserialize-default-on-null": 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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -8517,7 +9002,7 @@ ] }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -8548,17 +9033,19 @@ "type": "array", "items": { "type": "string" - } + }, + "x-deserialize-default-on-null": true }, "env": { "description": "Environment variables to set when launching the MCP server.", "type": "array", "items": { "$ref": "#/$defs/EnvVariable" - } + }, + "x-deserialize-default-on-null": 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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -8574,269 +9061,27 @@ "env" ] }, - "LoadSessionRequest": { - "description": "Request parameters for loading an existing session.\n\nOnly available if the Agent supports the `loadSession` capability.\n\nSee protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/session-setup#loading-sessions)", - "type": "object", - "properties": { - "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 - }, - "cwd": { - "description": "The working directory for this session. Must be an absolute path.", - "type": "string" - }, - "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 loaded\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": { - "type": "string" - }, - "x-deserialize-default-on-error": true, - "x-deserialize-skip-invalid-items": true - }, - "sessionId": { - "description": "The ID of the session to load.", - "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/extensibility)", - "type": [ - "object", - "null" - ], - "x-deserialize-default-on-error": true, - "additionalProperties": true - } - }, - "required": [ - "mcpServers", - "cwd", - "sessionId" - ], - "x-side": "agent", - "x-method": "session/load" - }, - "ListSessionsRequest": { - "description": "Request parameters for listing existing sessions.\n\nOnly available if the Agent supports the `sessionCapabilities.list` capability.", - "type": "object", - "properties": { - "cwd": { - "description": "Filter sessions by working directory. Must be an absolute path.", - "type": [ - "string", - "null" - ] - }, - "cursor": { - "description": "Opaque cursor token from a previous response's nextCursor field for cursor-based pagination", - "type": [ - "string", - "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/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 `sessionCapabilities.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/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.", - "type": "string" - }, - "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": { - "type": "string" - }, - "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/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 without returning previous messages (unlike `session/load`).\nThis is useful for agents that can resume sessions but don't implement full session loading.\n\nOnly available if the Agent supports the `sessionCapabilities.resume` capability.", + "SystemPrompt": { + "description": "Client-provided system-level instructions for a session.\n\nClients MUST only send this when the Agent advertises\n`sessionCapabilities.systemPrompt`. Agents that cannot apply it, for example\nbecause of an unadvertised mode or an unsupported content block type, MUST\nreturn an error instead of creating, loading, or resuming the session.", "type": "object", "properties": { - "sessionId": { - "description": "The ID of the session to resume.", + "mode": { + "description": "How the Agent combines `content` with its own instructions.\n\nRequired. Agents MUST return an error for a mode they do not support rather than\ntreating it as `append` or `override`.", "allOf": [ { - "$ref": "#/$defs/SessionId" + "$ref": "#/$defs/SystemPromptMode" } ] }, - "cwd": { - "description": "The working directory for this session. Must be an absolute path.", - "type": "string" - }, - "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": { - "type": "string" - }, - "x-deserialize-default-on-error": true, - "x-deserialize-skip-invalid-items": true - }, - "mcpServers": { - "description": "List of MCP servers to connect to for this session.", + "content": { + "description": "The system prompt content.\n\nAgents advertising the capability MUST accept `text` content blocks.\nClients MUST NOT send other content block types until a future\ncapability allows them, and Agents MUST return an error for content\nblocks they do not support.\n\nClients MUST NOT send an empty array. Agents MAY reject one with\n`-32602` without creating, loading, or resuming the 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/extensibility)", - "type": [ - "object", - "null" - ], - "x-deserialize-default-on-error": true, - "additionalProperties": true - } - }, - "required": [ - "sessionId", - "cwd" - ], - "x-side": "agent", - "x-method": "session/resume" - }, - "CloseSessionRequest": { - "description": "Request parameters for closing an active session.\n\nIf supported, the agent **must** cancel any ongoing work related to the session\n(treat it as if `session/cancel` was called) and then free up any resources\nassociated with the session.\n\nOnly available if the Agent supports the `sessionCapabilities.close` capability.", - "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/extensibility)", - "type": [ - "object", - "null" - ], - "x-deserialize-default-on-error": true, - "additionalProperties": true - } - }, - "required": [ - "sessionId" - ], - "x-side": "agent", - "x-method": "session/close" - }, - "SetSessionModeRequest": { - "description": "Request parameters for setting a session mode.", - "type": "object", - "properties": { - "sessionId": { - "description": "The ID of the session to set the mode for.", - "allOf": [ - { - "$ref": "#/$defs/SessionId" - } - ] - }, - "modeId": { - "description": "The ID of the mode to set.", - "allOf": [ - { - "$ref": "#/$defs/SessionModeId" - } - ] + "$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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -8846,24 +9091,34 @@ } }, "required": [ - "sessionId", - "modeId" - ], - "x-side": "agent", - "x-method": "session/set_mode" + "mode", + "content" + ] }, - "SetSessionConfigOptionRequest": { - "description": "Request parameters for setting a session configuration option.", + "SystemPromptMode": { + "description": "How the Agent combines a client-provided system prompt with its own instructions.\n\nUnknown modes are preserved so they can be stored,\nproxied, or forwarded. An Agent MUST return an error for a mode it does not\nsupport rather than treating it as `append` or `override`.", + "anyOf": [ + { + "description": "Add the content to the Agent's own instructions rather than replacing them.\n\nEvery Agent that advertises `sessionCapabilities.systemPrompt` supports this mode.\nAgents SHOULD give the content system-level precedence, for example in the\nmodel's system prompt or developer instructions rather than in user-turn\ncontent. Where it is placed and how it is formatted is implementation-defined.", + "type": "string", + "const": "append" + }, + { + "description": "Replace the Agent's built-in default instructions with the content.\n\nThis does not change tool availability, MCP servers, permissions, or session\nconfiguration. Context the Agent supplies from the workspace or environment\nMAY still be included. Clients that use this mode take responsibility for any\ntool guidance or safety instructions the Agent's default instructions\nprovided, and MUST only use it when the Agent advertises\n`sessionCapabilities.systemPrompt.mode.override`.", + "type": "string", + "const": "override" + }, + { + "title": "other", + "description": "Custom or future system prompt 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" + } + ] + }, + "InitialSessionConfigOption": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAn initial value for a config option, sent on session setup requests.\n\nSame shape as `session/set_config_option` without `sessionId`. Unlike\n`session/set_config_option`, an unknown `configId`, a `type` that does not match the\noption, or a value that is not allowed is ignored instead of rejected.\n\nClients only send `type: \"boolean\"` entries when they advertise\n`sessionCapabilities.configOptions.boolean`.", "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": [ @@ -8873,7 +9128,7 @@ ] }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -8883,7 +9138,6 @@ } }, "required": [ - "sessionId", "configId" ], "anyOf": [ @@ -8891,13 +9145,13 @@ "description": "A boolean value (`type: \"boolean\"`).", "type": "object", "properties": { - "value": { - "description": "The boolean value.", - "type": "boolean" - }, "type": { "type": "string", "const": "boolean" + }, + "value": { + "description": "The boolean value.", + "type": "boolean" } }, "required": [ @@ -8907,7 +9161,7 @@ }, { "title": "value_id", - "description": "A [`SessionConfigValueId`] string value.\n\nThis is the default when `type` is absent on the wire. Unknown `type`\nvalues with string payloads also gracefully deserialize into this\nvariant.", + "description": "A `SessionConfigValueId` string value.\n\nThis is the default when `type` is absent on the wire. Unknown `type`\nvalues with string payloads also gracefully deserialize into this\nvariant.", "type": "object", "properties": { "value": { @@ -8923,31 +9177,61 @@ "value" ] } - ], - "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/prompt-turn#1-user-message)", + "LoadSessionRequest": { + "description": "Request parameters for loading an existing session.\n\nOnly available if the Agent supports the `loadSession` capability.\n\nSee protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/v1/draft/session-setup#loading-sessions)", "type": "object", "properties": { + "mcpServers": { + "description": "List of MCP servers to connect to for this session.", + "type": "array", + "items": { + "$ref": "#/$defs/McpServer" + }, + "x-deserialize-default-on-null": true + }, + "cwd": { + "description": "The working directory for this session. Must be an absolute path.", + "type": "string" + }, + "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 loaded\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": { + "type": "string" + }, + "x-deserialize-default-on-null": true + }, "sessionId": { - "description": "The ID of the session to send this user message to", + "description": "The ID of the session to load.", "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.", + "systemPrompt": { + "description": "System-level instructions for the loaded session.\n\nOptional. Omitted and `null` are equivalent. The Agent may then keep a\nsystem prompt it stored with the session or use its default instructions.\nClients MUST only send this when the Agent advertises\n`sessionCapabilities.systemPrompt`, and SHOULD send the same value they used\nwhen the session was created.", + "anyOf": [ + { + "$ref": "#/$defs/SystemPrompt" + }, + { + "type": "null" + } + ] + }, + "configOptions": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial values for the session's config options.\n\nOptional. Omitted and `null` are equivalent to an empty list. Clients MUST only send\nthis when the Agent advertises `sessionCapabilities.options`.\n\nThe Agent applies the entries in list order, as if the Client had called\n`session/set_config_option` for each entry after the session was set up. Malformed\nentries and duplicate `configId` values fail the request with `-32602`. The Agent MUST\nignore an entry whose `configId` is unknown, whose `type` does not match the option,\nor whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually\nhas. The Agent SHOULD NOT send `config_option_update` notifications for these entries.", "type": "array", "items": { - "$ref": "#/$defs/ContentBlock" - } + "$ref": "#/$defs/InitialSessionConfigOption" + }, + "x-deserialize-default-on-null": 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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -8957,48 +9241,44 @@ } }, "required": [ - "sessionId", - "prompt" + "mcpServers", + "cwd", + "sessionId" ], "x-side": "agent", - "x-method": "session/prompt" + "x-method": "session/load" }, - "StartNesRequest": { - "description": "Request to start an NES session.", + "ListSessionsRequest": { + "description": "Request parameters for listing existing sessions.\n\nOnly available if the Agent supports the `sessionCapabilities.list` capability.", "type": "object", "properties": { - "workspaceUri": { - "description": "The root URI of the workspace.", + "cwd": { + "description": "Filter sessions by working directory. Must be an absolute path.", "type": [ "string", "null" - ], - "x-deserialize-default-on-error": true + ] }, - "workspaceFolders": { - "description": "The workspace folders.", + "cursor": { + "description": "Opaque cursor token from a previous response's nextCursor field for cursor-based pagination", "type": [ - "array", + "string", "null" - ], - "items": { - "$ref": "#/$defs/WorkspaceFolder" - } + ] }, - "repository": { - "description": "Repository metadata, if the workspace is a git repository.", + "archived": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nFilter sessions by archive state.\n\nOptional. Omitted and `null` are equivalent and mean `exclude`. Only send this when\nthe Agent advertises the `sessionCapabilities.archive` capability. The filter combines with `cwd` and\napplies before pagination. Clients keep the same value when following `nextCursor`.", "anyOf": [ { - "$ref": "#/$defs/NesRepository" + "$ref": "#/$defs/SessionArchiveFilter" }, { "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -9008,53 +9288,47 @@ } }, "x-side": "agent", - "x-method": "nes/start" + "x-method": "session/list" }, - "WorkspaceFolder": { - "description": "A workspace folder.", - "type": "object", - "properties": { - "uri": { - "description": "The URI of the folder.", - "type": "string" + "SessionArchiveFilter": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhich sessions `session/list` returns based on their archive state.\n\nUnknown values are preserved so they can be stored, proxied, or forwarded. An Agent MUST\nreturn `-32602` for a value it does not support rather than treating it as `exclude`.", + "anyOf": [ + { + "description": "Only sessions that are not archived. This is the default.", + "type": "string", + "const": "exclude" }, - "name": { - "description": "The display name of the folder.", - "type": "string" + { + "description": "Both archived sessions and sessions that are not archived.", + "type": "string", + "const": "include" }, - "_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/extensibility)", - "type": [ - "object", - "null" - ], - "x-deserialize-default-on-error": true, - "additionalProperties": true + { + "description": "Only archived sessions.", + "type": "string", + "const": "only" + }, + { + "title": "other", + "description": "Custom or future archive filter.\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": [ - "uri", - "name" ] }, - "NesRepository": { - "description": "Repository metadata for an NES session.", + "DeleteSessionRequest": { + "description": "Request parameters for deleting an existing session from `session/list`.\n\nOnly available if the Agent supports the `sessionCapabilities.delete` capability.", "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" + "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -9064,72 +9338,75 @@ } }, "required": [ - "name", - "owner", - "remoteUrl" - ] + "sessionId" + ], + "x-side": "agent", + "x-method": "session/delete" }, - "SuggestNesRequest": { - "description": "Request for a code suggestion.", + "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 session ID for this request.", + "description": "The ID of the session to fork.", "allOf": [ { "$ref": "#/$defs/SessionId" } ] }, - "uri": { - "description": "The URI of the document to suggest for.", - "type": "string" - }, - "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.", + "cursorId": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe session cursor to fork at. The new session's history is the source\nsession's history before the cursor.\n\nOptional. Omitted and `null` are equivalent and fork the whole session.\nClients MUST only send the ID of a cursor that the Agent announced on the\nsource session and that currently advertises `capabilities.fork`. The Agent\nrejects any other ID with `-32602`. It does not fall back to forking the\nwhole session.", "anyOf": [ { - "$ref": "#/$defs/Range" + "$ref": "#/$defs/CursorId" }, { "type": "null" } ] }, - "triggerKind": { - "description": "What triggered this suggestion request.", - "allOf": [ - { - "$ref": "#/$defs/NesTriggerKind" - } - ] + "cwd": { + "description": "The working directory for this session. Must be an absolute path.", + "type": "string" + }, + "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": { + "type": "string" + }, + "x-deserialize-default-on-null": true }, - "context": { - "description": "Context for the suggestion, included based on agent capabilities.", + "mcpServers": { + "description": "List of MCP servers to connect to for this session.", + "type": "array", + "items": { + "$ref": "#/$defs/McpServer" + }, + "x-deserialize-default-on-null": true + }, + "systemPrompt": { + "description": "System-level instructions for the forked session.\n\nOptional. Omitted and `null` are equivalent. The Agent may then keep a\nsystem prompt it stored with the source session or use its default\ninstructions. Clients MUST only send this when the Agent advertises\n`sessionCapabilities.systemPrompt`, and SHOULD send the same value they used\nfor the source session.", "anyOf": [ { - "$ref": "#/$defs/NesSuggestContext" + "$ref": "#/$defs/SystemPrompt" }, { "type": "null" } ] }, + "configOptions": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial values for the forked session's config options.\n\nOptional. Omitted and `null` are equivalent to an empty list. Clients MUST only send\nthis when the Agent advertises `sessionCapabilities.options`.\n\nThe Agent applies the entries in list order on top of the configuration the fork\nstarts with, as if the Client had called `session/set_config_option` for each entry\nafter the session was set up. Malformed entries and duplicate `configId` values fail\nthe request with `-32602`. The Agent MUST ignore an entry whose `configId` is unknown,\nwhose `type` does not match the option, or whose value is not allowed when it is\napplied. The `configOptions` in the response contain the values the session actually\nhas. The Agent SHOULD NOT send `config_option_update` notifications for these entries,\nand SHOULD NOT send other `session/update` notifications caused by applying them\nbefore it responds.", + "type": "array", + "items": { + "$ref": "#/$defs/InitialSessionConfigOption" + }, + "x-deserialize-default-on-null": 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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -9140,100 +9417,53 @@ }, "required": [ "sessionId", - "uri", - "version", - "position", - "triggerKind" + "cwd" ], "x-side": "agent", - "x-method": "nes/suggest" - }, - "NesTriggerKind": { - "description": "What triggered the suggestion request.", - "oneOf": [ - { - "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" - } - ] + "x-method": "session/fork" }, - "NesSuggestContext": { - "description": "Context attached to a suggestion request.", + "ArchiveSessionRequest": { + "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 archiving a session.\n\nOnly available if the Agent supports the `sessionCapabilities.archive` capability.\n\nArchiving hides the session from default `session/list` results. It keeps the session ID\nand saved history. If the session is active, the Agent MUST cancel any ongoing work and\nfree the session's resources as if `session/close` had been called, then archive it.\nArchiving an archived session succeeds. A session that does not exist gets `-32002`.", "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" - } + "sessionId": { + "description": "The ID of the session to archive.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] }, - "diagnostics": { - "description": "Current diagnostics (errors, warnings).", + "_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/v1/draft/extensibility)", "type": [ - "array", + "object", "null" ], - "items": { - "$ref": "#/$defs/NesDiagnostic" - } + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "sessionId" + ], + "x-side": "agent", + "x-method": "session/archive" + }, + "UnarchiveSessionRequest": { + "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 unarchiving a session.\n\nOnly available if the Agent supports the `sessionCapabilities.archive` capability.\n\nUnarchiving returns the session to default `session/list` results with the same ID and\nsaved history. It never loads or resumes the session. Clients that want to continue an\narchived session SHOULD unarchive it before calling `session/load` or `session/resume`.\nUnarchiving a session that is not archived succeeds. A session that does not exist\ngets `-32002`.", + "type": "object", + "properties": { + "sessionId": { + "description": "The ID of the session to unarchive.", + "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -9241,26 +9471,27 @@ "x-deserialize-default-on-error": true, "additionalProperties": true } - } + }, + "required": [ + "sessionId" + ], + "x-side": "agent", + "x-method": "session/unarchive" }, - "NesRecentFile": { - "description": "A recently accessed file.", + "SessionStatusRequest": { + "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 checking the status of a session.\n\nOnly available if the Agent supports the `sessionCapabilities.status` capability.\n\n`session/status` MUST NOT have side effects. The Agent does not load, resume, create,\nclose, or change the session, and does not attach the requesting connection to it.\nA session the Agent does not know gets `-32002` with the requested `sessionId` in `data`.", "type": "object", "properties": { - "uri": { - "description": "The URI of the file.", - "type": "string" - }, - "languageId": { - "description": "The language identifier.", - "type": "string" - }, - "text": { - "description": "The full text content of the file.", - "type": "string" + "sessionId": { + "description": "The ID of the session to check.", + "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -9270,28 +9501,40 @@ } }, "required": [ - "uri", - "languageId", - "text" - ] + "sessionId" + ], + "x-side": "agent", + "x-method": "session/status" }, - "NesRelatedSnippet": { - "description": "A related code snippet from a file.", + "SessionOptionsRequest": { + "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 `session/options`, which returns the config options a session\nwould start with, without creating or resuming a session.\n\nOnly available if the Agent supports the `sessionCapabilities.options` capability.\n\n`session/options` MUST NOT create or resume a session, send `session/update`\nnotifications, add an entry to `session/list`, or change an existing session. Agents\nSHOULD NOT connect to MCP servers to answer it. Agents MAY start their runtime to resolve\nthe options. The rules above still hold for it.", "type": "object", "properties": { - "uri": { - "description": "The URI of the file containing the snippets.", + "cwd": { + "description": "The working directory to resolve options for. Must be an absolute path.", "type": "string" }, - "excerpts": { - "description": "The code excerpts.", + "additionalDirectories": { + "description": "Additional workspace roots to resolve options for. Each path must be absolute.\n\nOptional. Omitted and `null` are equivalent to an empty list.", "type": "array", "items": { - "$ref": "#/$defs/NesExcerpt" - } + "type": "string" + }, + "x-deserialize-default-on-null": true + }, + "sessionId": { + "description": "The session to resolve options for.\n\nOptional. Omitted and `null` are equivalent and mean a new session. When present,\nthe Agent returns what `session/load` or `session/resume` with the same `cwd` and\n`additionalDirectories` would return, with the same `cwd` rules. A session the\nAgent does not know gets `-32002`.\nClients MUST only send this when the Agent supports `session/load` (`loadSession`)\nor `session/resume` (`sessionCapabilities.resume`).", + "anyOf": [ + { + "$ref": "#/$defs/SessionId" + }, + { + "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -9301,32 +9544,29 @@ } }, "required": [ - "uri", - "excerpts" - ] + "cwd" + ], + "x-side": "agent", + "x-method": "session/options" }, - "NesExcerpt": { - "description": "A code excerpt from a file.", + "SetSessionTitleRequest": { + "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 setting the title of a session.\n\nOnly available if the Agent supports the `sessionCapabilities.title` capability.\n\nThe session does not need to be active on the connection. Any session the Agent would\nreturn from `session/list` can be retitled. A session that does not exist gets `-32002`.\n\nThe Agent responds only after it has stored the title. After a successful response, the\nAgent SHOULD NOT replace the title with one it generates automatically.", "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 + "sessionId": { + "description": "The ID of the session to retitle.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] }, - "text": { - "description": "The text content of the excerpt.", + "title": { + "description": "The new title for the session.\n\nRequired and non-null. Omission and explicit `null` are both invalid. The Agent MAY\nnormalize the title before storing it, for example by trimming whitespace or\ntruncating it. The Agent rejects a title that fails its validation, including one\nthat is empty after normalization, with `-32602`.", "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -9336,25 +9576,65 @@ } }, "required": [ - "startLine", - "endLine", - "text" - ] + "sessionId", + "title" + ], + "x-side": "agent", + "x-method": "session/set_title" }, - "NesEditHistoryEntry": { - "description": "An entry in the edit history.", + "ResumeSessionRequest": { + "description": "Request parameters for resuming an existing session.\n\nResumes an existing session without returning previous messages (unlike `session/load`).\nThis is useful for agents that can resume sessions but don't implement full session loading.\n\nOnly available if the Agent supports the `sessionCapabilities.resume` capability.", "type": "object", "properties": { - "uri": { - "description": "The URI of the edited file.", - "type": "string" + "sessionId": { + "description": "The ID of the session to resume.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] }, - "diff": { - "description": "A diff representing the edit.", + "cwd": { + "description": "The working directory for this session. Must be an absolute path.", "type": "string" }, + "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": { + "type": "string" + }, + "x-deserialize-default-on-null": true + }, + "mcpServers": { + "description": "List of MCP servers to connect to for this session.", + "type": "array", + "items": { + "$ref": "#/$defs/McpServer" + }, + "x-deserialize-default-on-null": true + }, + "systemPrompt": { + "description": "System-level instructions for the resumed session.\n\nOptional. Omitted and `null` are equivalent. The Agent may then keep a\nsystem prompt it stored with the session or use its default instructions.\nClients MUST only send this when the Agent advertises\n`sessionCapabilities.systemPrompt`, and SHOULD send the same value they used\nwhen the session was created.", + "anyOf": [ + { + "$ref": "#/$defs/SystemPrompt" + }, + { + "type": "null" + } + ] + }, + "configOptions": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nInitial values for the session's config options.\n\nOptional. Omitted and `null` are equivalent to an empty list. Clients MUST only send\nthis when the Agent advertises `sessionCapabilities.options`.\n\nThe Agent applies the entries in list order, as if the Client had called\n`session/set_config_option` for each entry after the session was set up. Malformed\nentries and duplicate `configId` values fail the request with `-32602`. The Agent MUST\nignore an entry whose `configId` is unknown, whose `type` does not match the option,\nor whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually\nhas. The Agent SHOULD NOT send `config_option_update` notifications for these entries.", + "type": "array", + "items": { + "$ref": "#/$defs/InitialSessionConfigOption" + }, + "x-deserialize-default-on-null": 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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -9364,38 +9644,26 @@ } }, "required": [ - "uri", - "diff" - ] + "sessionId", + "cwd" + ], + "x-side": "agent", + "x-method": "session/resume" }, - "NesUserAction": { - "description": "A user action (typing, cursor movement, etc.).", + "CloseSessionRequest": { + "description": "Request parameters for closing an active session.\n\nIf supported, the agent **must** cancel any ongoing work related to the session\n(treat it as if `session/cancel` was called) and then free up any resources\nassociated with the session.\n\nOnly available if the Agent supports the `sessionCapabilities.close` capability.", "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" - }, - "position": { - "description": "The position where the action occurred.", + "sessionId": { + "description": "The ID of the session to close.", "allOf": [ { - "$ref": "#/$defs/Position" + "$ref": "#/$defs/SessionId" } ] }, - "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -9405,48 +9673,33 @@ } }, "required": [ - "action", - "uri", - "position", - "timestampMs" - ] + "sessionId" + ], + "x-side": "agent", + "x-method": "session/close" }, - "NesOpenFile": { - "description": "An open file in the editor.", + "SetSessionModeRequest": { + "description": "Request parameters for setting a session mode.", "type": "object", "properties": { - "uri": { - "description": "The URI of the file.", - "type": "string" - }, - "languageId": { - "description": "The language identifier.", - "type": "string" - }, - "visibleRange": { - "description": "The visible range in the editor, if any.", - "anyOf": [ - { - "$ref": "#/$defs/Range" - }, + "sessionId": { + "description": "The ID of the session to set the mode for.", + "allOf": [ { - "type": "null" + "$ref": "#/$defs/SessionId" } - ], - "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 + "modeId": { + "description": "The ID of the mode to set.", + "allOf": [ + { + "$ref": "#/$defs/SessionModeId" + } + ] }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -9456,40 +9709,34 @@ } }, "required": [ - "uri", - "languageId" - ] + "sessionId", + "modeId" + ], + "x-side": "agent", + "x-method": "session/set_mode" }, - "NesDiagnostic": { - "description": "A diagnostic (error, warning, etc.).", + "SetSessionConfigOptionRequest": { + "description": "Request parameters for setting a session configuration option.", "type": "object", "properties": { - "uri": { - "description": "The URI of the file containing the diagnostic.", - "type": "string" - }, - "range": { - "description": "The range of the diagnostic.", + "sessionId": { + "description": "The ID of the session to set the configuration option for.", "allOf": [ { - "$ref": "#/$defs/Range" + "$ref": "#/$defs/SessionId" } ] }, - "severity": { - "description": "The severity of the diagnostic.", + "configId": { + "description": "The ID of the configuration option to set.", "allOf": [ { - "$ref": "#/$defs/NesDiagnosticSeverity" + "$ref": "#/$defs/SessionConfigId" } ] }, - "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -9499,51 +9746,71 @@ } }, "required": [ - "uri", - "range", - "severity", - "message" - ] - }, - "NesDiagnosticSeverity": { - "description": "Severity of a diagnostic.", - "oneOf": [ - { - "description": "An error.", - "type": "string", - "const": "error" - }, - { - "description": "A warning.", - "type": "string", - "const": "warning" - }, + "sessionId", + "configId" + ], + "anyOf": [ { - "description": "An informational message.", - "type": "string", - "const": "information" + "description": "A boolean value (`type: \"boolean\"`).", + "type": "object", + "properties": { + "type": { + "type": "string", + "const": "boolean" + }, + "value": { + "description": "The boolean value.", + "type": "boolean" + } + }, + "required": [ + "type", + "value" + ] }, { - "description": "A hint.", - "type": "string", - "const": "hint" + "title": "value_id", + "description": "A `SessionConfigValueId` string value.\n\nThis is the default when `type` is absent on the wire. Unknown `type`\nvalues with string payloads also gracefully deserialize into this\nvariant.", + "type": "object", + "properties": { + "value": { + "description": "The value ID.", + "allOf": [ + { + "$ref": "#/$defs/SessionConfigValueId" + } + ] + } + }, + "required": [ + "value" + ] } - ] + ], + "x-side": "agent", + "x-method": "session/set_config_option" }, - "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.", + "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/v1/draft/prompt-turn#1-user-message)", "type": "object", "properties": { "sessionId": { - "description": "The ID of the NES session to close.", + "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 `text` and `resource_link` content blocks,\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`resource` or `resource_link` content blocks.\n\nWhen available, `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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -9553,10 +9820,11 @@ } }, "required": [ - "sessionId" + "sessionId", + "prompt" ], "x-side": "agent", - "x-method": "nes/close" + "x-method": "session/prompt" }, "ClientResponse": { "description": "A JSON-RPC response object.", @@ -9719,7 +9987,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -9740,7 +10008,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -9768,7 +10036,7 @@ ] }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -9787,7 +10055,7 @@ "description": "The outcome of a permission request.", "oneOf": [ { - "description": "The prompt turn was cancelled before the user responded.\n\nWhen a client sends a `session/cancel` notification to cancel an ongoing\nprompt turn, it MUST respond to all pending `session/request_permission`\nrequests with this `Cancelled` outcome.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation)", + "description": "The prompt turn was cancelled before the user responded.\n\nWhen a client sends a `session/cancel` notification to cancel an ongoing\nprompt turn, it MUST respond to all pending `session/request_permission`\nrequests with this `cancelled` outcome.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v1/draft/prompt-turn#cancellation)", "type": "object", "properties": { "outcome": { @@ -9835,7 +10103,7 @@ ] }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -9861,7 +10129,7 @@ ] }, "_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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -9901,7 +10169,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -9940,7 +10208,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -9955,7 +10223,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -9990,7 +10258,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -10007,7 +10275,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -10024,7 +10292,7 @@ "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -10138,7 +10406,7 @@ "x-method": "elicitation/create" }, "ElicitationContentValue": { - "description": "Allowed wire representations for [`ElicitationContentValue`].", + "description": "Allowed wire representations for `ElicitationContentValue`.", "anyOf": [ { "title": "String", @@ -10189,7 +10457,7 @@ } }, "MessageMcpResponse": { - "description": "**UNSTABLE**\n\nThe successful outer ACP `mcp/message` response carries exactly one\ninner MCP outcome: an opaque result (including JSON null), or an MCP error.\nOuter ACP errors are reserved for binding and runtime failures.\n\nBoth branches require their carrier key. An error must be a non-null object.\nUnknown outer fields are ignored; inner result and error fields are preserved.\nCarrier `_meta` is optional; null or invalid values are treated as absent.\nSenders must include exactly one outcome; receivers prefer `result` if both are present.", + "description": "**UNSTABLE**\n\nThe successful outer ACP `mcp/message` response carries exactly one\ninner MCP outcome: an opaque result (including JSON null), or an MCP error.\nOuter ACP errors are reserved for binding and runtime failures.\n\nBoth branches require their carrier key. An error must be a non-null object.\nUnknown outer fields are ignored. Inner result and error fields are preserved.\nCarrier `_meta` is optional. Null or invalid values are treated as absent.\nSenders must include exactly one outcome. Receivers prefer `result` if both are present.", "anyOf": [ { "title": "Result", @@ -10245,11 +10513,11 @@ "x-method": "mcp/message" }, "McpError": { - "description": "**UNSTABLE**\n\nAn inner MCP error, distinct from an outer ACP binding or runtime error.\n\n`code` and `message` are required and non-null. `data` is optional;\nexplicit `null` is preserved separately from an omitted key.", + "description": "**UNSTABLE**\n\nAn inner MCP error, distinct from an outer ACP binding or runtime error.\n\n`code` and `message` are required and non-null. `data` is optional.\nExplicit `null` is preserved separately from an omitted key.", "type": "object", "properties": { "code": { - "description": "Inner MCP error code; never an ACP error code.", + "description": "Inner MCP error code. Never an ACP error code.", "type": "integer", "format": "int32" }, @@ -10258,7 +10526,7 @@ "type": "string" }, "data": { - "description": "Optional error data; explicit null is retained." + "description": "Optional error data. Explicit null is retained." } }, "required": [ @@ -10283,76 +10551,13 @@ "anyOf": [ { "title": "CancelNotification", - "description": "Cancels ongoing operations for a session.\n\nThis is a notification sent by the client to cancel an ongoing prompt turn.\n\nUpon receiving this notification, the Agent SHOULD:\n- Stop all language model requests as soon as possible\n- Abort all tool call invocations in progress\n- Send any pending `session/update` notifications\n- Respond to the original `session/prompt` request with `StopReason::Cancelled`\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation)", + "description": "Cancels ongoing operations for a session.\n\nThis is a notification sent by the client to cancel an ongoing prompt turn.\n\nUpon receiving this notification, the Agent SHOULD:\n- Stop all language model requests as soon as possible\n- Abort all tool call invocations in progress\n- Send any pending `session/update` notifications\n- Respond to the original `session/prompt` request with the `cancelled` stop reason\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v1/draft/prompt-turn#cancellation)", "allOf": [ { "$ref": "#/$defs/CancelNotification" } ] }, - { - "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.", @@ -10364,7 +10569,7 @@ }, { "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/extensibility)", + "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/v1/draft/extensibility)", "allOf": [ { "$ref": "#/$defs/ExtNotification" @@ -10380,274 +10585,24 @@ } }, "required": [ - "method" - ], - "x-docs-ignore": true - }, - "CancelNotification": { - "description": "Notification to cancel ongoing operations for a session.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#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/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" - }, - "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/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" - }, - "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/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/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" - }, - "_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/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" - }, - "_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/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" - }, - "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.", + "method" + ], + "x-docs-ignore": true + }, + "CancelNotification": { + "description": "Notification to cancel ongoing operations for a session.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v1/draft/prompt-turn#cancellation)", + "type": "object", + "properties": { + "sessionId": { + "description": "The ID of the session to cancel operations for.", "allOf": [ { - "$ref": "#/$defs/Range" + "$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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -10657,37 +10612,45 @@ } }, "required": [ - "sessionId", - "uri", - "version", - "position", - "visibleRange" + "sessionId" ], "x-side": "agent", - "x-method": "document/didFocus" + "x-method": "session/cancel" }, - "AcceptNesNotification": { - "description": "Notification sent when a suggestion is accepted.", + "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\nSent by the provider to the consumer for an active request (including\nsubscription acknowledgements and updates). The outer envelope has no `id`.", "type": "object", "properties": { - "sessionId": { - "description": "The session ID for this notification.", + "serverId": { + "description": "The declared ACP MCP server handling the associated request.", "allOf": [ { - "$ref": "#/$defs/SessionId" + "$ref": "#/$defs/McpServerAcpId" } ] }, - "id": { - "description": "The ID of the accepted suggestion.", + "requestId": { + "description": "The identifier of the active inner MCP request.", "allOf": [ { - "$ref": "#/$defs/NesSuggestionId" + "$ref": "#/$defs/McpRequestId" } ] }, + "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/extensibility)", + "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/v1/draft/extensibility)", "type": [ "object", "null" @@ -10697,120 +10660,118 @@ } }, "required": [ - "sessionId", - "id" + "serverId", + "requestId", + "method" ], "x-side": "agent", - "x-method": "nes/accept" + "x-method": "mcp/message" }, - "RejectNesNotification": { - "description": "Notification sent when a suggestion is rejected.", + "CancelRequestNotification": { + "description": "Notification to cancel an ongoing request.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/v1/draft/cancellation)", "type": "object", "properties": { - "sessionId": { - "description": "The session ID for this notification.", + "requestId": { + "description": "The ID of the request to cancel.", "allOf": [ { - "$ref": "#/$defs/SessionId" + "$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/v1/draft/extensibility)", + "type": [ + "object", + "null" + ], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": [ + "requestId" + ], + "x-side": "protocol", + "x-method": "$/cancel_request" + }, + "ProxyRequest": { + "description": "A JSON-RPC request object.", + "type": "object", + "properties": { "id": { - "description": "The ID of the rejected suggestion.", + "description": "The request id used to correlate the matching response.", "allOf": [ { - "$ref": "#/$defs/NesSuggestionId" + "$ref": "#/$defs/RequestId" } ] }, - "reason": { - "description": "The reason for rejection.", + "method": { + "description": "The method name to invoke.", + "type": "string" + }, + "params": { + "description": "Method-specific request parameters.", "anyOf": [ { - "$ref": "#/$defs/NesRejectReason" + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequests exchanged between a conductor and its proxies.\n\nA conductor sends `proxy/initialize` and `proxy/successor` to a proxy. A proxy sends\n`proxy/successor` to its conductor.", + "anyOf": [ + { + "title": "InitializeProxyRequest", + "description": "Initializes a component as a proxy.\n\nSent by a conductor to each component that has a successor, instead of `initialize`.\nThe params and response are the same as for `initialize`.", + "allOf": [ + { + "$ref": "#/$defs/InitializeProxyRequest" + } + ] + }, + { + "title": "ProxySuccessorRequest", + "description": "Forwards a request to or from a proxy's successor.\n\nA proxy sends it to its conductor to forward a request downstream. The conductor sends\nit to the proxy to deliver a request from the successor. The wrapped request's result\nor error is returned unchanged.", + "allOf": [ + { + "$ref": "#/$defs/ProxySuccessorRequest" + } + ] + } + ] }, { "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/extensibility)", - "type": [ - "object", - "null" - ], - "x-deserialize-default-on-error": true, - "additionalProperties": true + ] } }, "required": [ - "sessionId", - "id" + "id", + "method" ], - "x-side": "agent", - "x-method": "nes/reject" + "x-docs-ignore": true }, - "NesRejectReason": { - "description": "The reason a suggestion was rejected.", - "oneOf": [ - { - "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" - }, + "InitializeProxyRequest": { + "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 `proxy/initialize`.\n\nA conductor sends `proxy/initialize` instead of `initialize` to every component that has a\nsuccessor, which tells the component to run as a proxy. The params and the response are\nthe same as for `initialize`. A conductor sends `initialize` to the final agent.\n\nThe params carry the protocol version the conductor selected: the client's requested\nversion, unless the conductor supports only a lower one. Before answering successfully,\nthe proxy MUST forward an `initialize` request to its successor through `proxy/successor`.\n\nSee the [Proxy Chains RFD](https://agentclientprotocol.com/rfds/proxy-chains).", + "x-method": "proxy/initialize", + "x-side": "proxy", + "allOf": [ { - "description": "The request was cancelled before the agent returned a response.", - "type": "string", - "const": "cancelled" + "$ref": "#/$defs/InitializeRequest" } ] }, - "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\nSent by the provider to the consumer for an active request (including\nsubscription acknowledgements and updates); the outer envelope has no `id`.", + "ProxySuccessorRequest": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nParameters of a `proxy/successor` request.\n\nA proxy sends it to forward a message to its successor, and the conductor sends it to\ndeliver a message from the successor to the proxy. The envelope wraps one request: `method`\nand `params` are the wrapped request's method and params.\n\nThe result or error of the wrapped request is returned unchanged, as the same JSON value,\nas the result or error of the `proxy/successor` request. Errors the conductor returns\nitself, for example because the successor has exited, are not wrapped results.\n\nTo cancel it, the sender sends `$/cancel_request` with the ID of this `proxy/successor`\nrequest on the same connection. Cancellation is never forwarded to another hop.\n\nSee the [Proxy Chains RFD](https://agentclientprotocol.com/rfds/proxy-chains).", "type": "object", "properties": { - "serverId": { - "description": "The declared ACP MCP server handling the associated request.", - "allOf": [ - { - "$ref": "#/$defs/McpServerAcpId" - } - ] - }, - "requestId": { - "description": "The identifier of the active inner MCP request.", - "allOf": [ - { - "$ref": "#/$defs/McpRequestId" - } - ] - }, "method": { - "description": "The inner MCP method name.", + "description": "Method name of the wrapped request.", "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 + "description": "Params of the wrapped request, forwarded unchanged.\n\nOptional. Omitted and `null` are equivalent and mean the wrapped request has no params.\nWhen present, it MUST be a JSON object or array, as JSON-RPC requires.\nThe wrapped request's own `_meta` stays inside these params." }, "_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/extensibility)", + "description": "Metadata for the `proxy/successor` envelope itself, separate from the wrapped\nmessage's `_meta`. It is hop-local: the conductor does not copy it into the message\nit unwraps.\n\nThe _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/v1/draft/extensibility)", "type": [ "object", "null" @@ -10820,27 +10781,150 @@ } }, "required": [ - "serverId", - "requestId", "method" ], - "x-side": "agent", - "x-method": "mcp/message" + "x-side": "proxy", + "x-method": "proxy/successor" }, - "CancelRequestNotification": { - "description": "Notification to cancel an ongoing request.\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation)", + "ProxyResponse": { + "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": "InitializeProxyResponse", + "description": "Successful result returned for a `proxy/initialize` request.", + "allOf": [ + { + "$ref": "#/$defs/InitializeProxyResponse" + } + ] + }, + { + "title": "ProxySuccessorResponse", + "description": "Successful result returned for a `proxy/successor` request.", + "allOf": [ + { + "$ref": "#/$defs/ProxySuccessorResponse" + } + ] + } + ] + } + }, + "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 + }, + "InitializeProxyResponse": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse to `proxy/initialize`.\n\nThe same as the `initialize` response. The proxy builds it from its successor's\n`initialize` response and answers with the capabilities of the chain from itself onward.\nIt MUST NOT change `protocolVersion`.", + "x-method": "proxy/initialize", + "x-side": "proxy", + "allOf": [ + { + "$ref": "#/$defs/InitializeResponse" + } + ] + }, + "ProxySuccessorResponse": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResult of a `proxy/successor` request: the wrapped request's result, forwarded unchanged.", + "x-side": "proxy", + "x-method": "proxy/successor" + }, + "ProxyNotification": { + "description": "A JSON-RPC notification object.", "type": "object", "properties": { - "requestId": { - "description": "The ID of the request to cancel.", - "allOf": [ + "method": { + "description": "The notification method name.", + "type": "string" + }, + "params": { + "description": "Method-specific notification parameters.", + "anyOf": [ { - "$ref": "#/$defs/RequestId" + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nNotifications exchanged between a conductor and its proxies.", + "anyOf": [ + { + "title": "ProxySuccessorNotification", + "description": "Forwards a notification to or from a proxy's successor.\n\nA proxy sends it to its conductor to forward a notification downstream. The conductor\nsends it to the proxy to deliver a notification from the successor.", + "allOf": [ + { + "$ref": "#/$defs/ProxySuccessorNotification" + } + ] + } + ] + }, + { + "type": "null" } ] + } + }, + "required": [ + "method" + ], + "x-docs-ignore": true + }, + "ProxySuccessorNotification": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nParameters of a `proxy/successor` notification.\n\nA proxy sends it to forward a message to its successor, and the conductor sends it to\ndeliver a message from the successor to the proxy. The envelope wraps one notification: `method`\nand `params` are the wrapped notification's method and params.\n\nSee the [Proxy Chains RFD](https://agentclientprotocol.com/rfds/proxy-chains).", + "type": "object", + "properties": { + "method": { + "description": "Method name of the wrapped notification.", + "type": "string" + }, + "params": { + "description": "Params of the wrapped notification, forwarded unchanged.\n\nOptional. Omitted and `null` are equivalent and mean the wrapped notification has no params.\nWhen present, it MUST be a JSON object or array, as JSON-RPC requires.\nThe wrapped notification's own `_meta` stays inside these params." }, "_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/extensibility)", + "description": "Metadata for the `proxy/successor` envelope itself, separate from the wrapped\nmessage's `_meta`. It is hop-local: the conductor does not copy it into the message\nit unwraps.\n\nThe _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/v1/draft/extensibility)", "type": [ "object", "null" @@ -10850,10 +10934,10 @@ } }, "required": [ - "requestId" + "method" ], - "x-side": "protocol", - "x-method": "$/cancel_request" + "x-side": "proxy", + "x-method": "proxy/successor" } } } diff --git a/scripts/gen_schema_v1.py b/scripts/gen_schema_v1.py index fe655b9f..86ed167c 100644 --- a/scripts/gen_schema_v1.py +++ b/scripts/gen_schema_v1.py @@ -50,18 +50,7 @@ "PlanUpdateContent", "oneOf", "allOf", - ("PlanUpdateItems", "PlanUpdateFile", "PlanUpdateMarkdown"), - ), - variant_model_map( - "NesSuggestion", - "oneOf", - "allOf", - ( - "NesEditSuggestionVariant", - "NesJumpSuggestionVariant", - "NesRenameSuggestionVariant", - "NesSearchAndReplaceSuggestionVariant", - ), + ("PlanUpdateItems", "PlanUpdateMarkdown"), ), variant_model_map( "SessionUpdate", diff --git a/src/acp/__init__.py b/src/acp/__init__.py index ede36b13..d12334c8 100644 --- a/src/acp/__init__.py +++ b/src/acp/__init__.py @@ -14,13 +14,10 @@ ) from .schema import ( AcceptElicitationResponse, - AcceptNesNotification, AuthenticateRequest, AuthenticateResponse, CancelElicitationResponse, CancelNotification, - CloseNesRequest, - CloseNesResponse, CompleteElicitationNotification, CreateElicitationRequest, CreateElicitationResponse, @@ -36,11 +33,6 @@ DeclineElicitationResponse, DeleteSessionRequest, DeleteSessionResponse, - DidChangeDocumentNotification, - DidCloseDocumentNotification, - DidFocusDocumentNotification, - DidOpenDocumentNotification, - DidSaveDocumentNotification, DisableProviderRequest, DisableProviderResponse, ElicitationBooleanPropertySchema, @@ -81,7 +73,6 @@ PromptResponse, ReadTextFileRequest, ReadTextFileResponse, - RejectNesNotification, ReleaseTerminalRequest, ReleaseTerminalResponse, RequestPermissionRequest, @@ -93,10 +84,6 @@ SetSessionConfigOptionSelectRequest, SetSessionModeRequest, SetSessionModeResponse, - StartNesRequest, - StartNesResponse, - SuggestNesRequest, - SuggestNesResponse, TerminalOutputRequest, TerminalOutputResponse, WaitForTerminalExitRequest, @@ -126,16 +113,8 @@ "AGENT_METHODS", "CLIENT_METHODS", # types - "AcceptNesNotification", - "CloseNesRequest", - "CloseNesResponse", "DeleteSessionRequest", "DeleteSessionResponse", - "DidChangeDocumentNotification", - "DidCloseDocumentNotification", - "DidFocusDocumentNotification", - "DidOpenDocumentNotification", - "DidSaveDocumentNotification", "DisableProviderRequest", "DisableProviderResponse", "ListProvidersRequest", @@ -148,13 +127,8 @@ "McpResultResponse", "McpErrorResponse", "McpError", - "RejectNesNotification", "SetProviderRequest", "SetProviderResponse", - "StartNesRequest", - "StartNesResponse", - "SuggestNesRequest", - "SuggestNesResponse", "InitializeRequest", "InitializeResponse", "NewSessionRequest", diff --git a/src/acp/agent/connection.py b/src/acp/agent/connection.py index 9646fb0a..0b06f271 100644 --- a/src/acp/agent/connection.py +++ b/src/acp/agent/connection.py @@ -17,6 +17,8 @@ AgentPlanRemovedUpdate, AgentPlanUpdate, AgentThoughtChunk, + AuthAccount, + AuthStatusUpdateNotification, AvailableCommandsUpdate, CancelElicitationResponse, CompleteElicitationNotification, @@ -53,7 +55,9 @@ SessionNotification, SessionUpdateCompactionSummaryChunk, SessionUpdateCompactionUpdate, + SessionUpdateCursorUpdate, SessionUpdateNotice, + SessionUpdatePromptSuggestionsUpdate, SessionUpdateSessionMessage, SessionUpdateSessionMessageChunk, SessionUpdateSubagentUpdate, @@ -69,14 +73,7 @@ WriteTextFileRequest, WriteTextFileResponse, ) -from ..utils import ( - compatible_class, - notify_model, - param_model, - request_model, - request_optional_model, - serialize_params, -) +from ..utils import compatible_class, notify_model, param_model, request_model, request_optional_model, serialize_params from .router import build_agent_router __all__ = ["AgentSideConnection"] @@ -128,16 +125,13 @@ def attach( agent, handler = self._prepare(to_agent, use_unstable_protocol=use_unstable_protocol) self._conn = connection self._notify_connected(agent) - return self, handler + return (self, handler) def _prepare( - self, - to_agent: Callable[[AgentSideConnection], Agent] | Agent, - *, - use_unstable_protocol: bool, + self, to_agent: Callable[[AgentSideConnection], Agent] | Agent, *, use_unstable_protocol: bool ) -> tuple[Agent, MethodHandler]: agent = cast(Agent, to_agent(self) if callable(to_agent) else to_agent) - return agent, build_agent_router(agent, use_unstable_protocol=use_unstable_protocol) + return (agent, build_agent_router(agent, use_unstable_protocol=use_unstable_protocol)) def _notify_connected(self, agent: Agent) -> None: if on_connect := getattr(agent, "on_connect", None): @@ -167,6 +161,8 @@ async def session_update( | SessionUpdateNotice | SessionUpdateCompactionUpdate | SessionUpdateCompactionSummaryChunk + | SessionUpdatePromptSuggestionsUpdate + | SessionUpdateCursorUpdate | SessionUpdateSubagentUpdate | SessionUpdateSessionMessage | SessionUpdateSessionMessageChunk, @@ -294,6 +290,14 @@ async def complete_elicitation(self, elicitation_id: str, **kwargs: Any) -> None CompleteElicitationNotification(elicitation_id=elicitation_id, field_meta=kwargs or None), ) + @param_model(AuthStatusUpdateNotification) + async def auth_status_update(self, state: str, accounts: list[AuthAccount] | None = None, **kwargs: Any) -> None: + await notify_model( + self._conn, + CLIENT_METHODS["auth_status_update"], + AuthStatusUpdateNotification(state=state, accounts=accounts, field_meta=kwargs or None), + ) + @param_model(MessageMcpRequest) async def mcp_message( self, server_id: str, request_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any diff --git a/src/acp/client/connection.py b/src/acp/client/connection.py index 5135341a..26d59fa8 100644 --- a/src/acp/client/connection.py +++ b/src/acp/client/connection.py @@ -12,24 +12,20 @@ from ..meta import AGENT_METHODS, CLIENT_METHODS from ..router import _resolve_handler, _warn_legacy_handler from ..schema import ( - AcceptNesNotification, AcpMcpServer, + ArchiveSessionRequest, + ArchiveSessionResponse, AudioContentBlock, AuthenticateRequest, AuthenticateResponse, + AuthStatusRequest, + AuthStatusResponse, CancelNotification, ClientCapabilities, - CloseNesRequest, - CloseNesResponse, CloseSessionRequest, CloseSessionResponse, DeleteSessionRequest, DeleteSessionResponse, - DidChangeDocumentNotification, - DidCloseDocumentNotification, - DidFocusDocumentNotification, - DidOpenDocumentNotification, - DidSaveDocumentNotification, DisableProviderRequest, DisableProviderResponse, EmbeddedResourceContentBlock, @@ -40,6 +36,8 @@ Implementation, InitializeRequest, InitializeResponse, + InitialSessionConfigOption1, + InitialSessionConfigOption2, ListProvidersRequest, ListProvidersResponse, ListSessionsRequest, @@ -50,19 +48,18 @@ LogoutResponse, McpServerStdio, MessageMcpNotification, - NesRepository, - NesSuggestContext, NewSessionRequest, NewSessionResponse, - Position, PromptRequest, PromptResponse, - Range, - RejectNesNotification, ResourceContentBlock, ResumeSessionRequest, ResumeSessionResponse, SessionNotification, + SessionOptionsRequest, + SessionOptionsResponse, + SessionStatusRequest, + SessionStatusResponse, SetProviderRequest, SetProviderResponse, SetSessionConfigOptionBooleanRequest, @@ -70,22 +67,15 @@ SetSessionConfigOptionSelectRequest, SetSessionModeRequest, SetSessionModeResponse, + SetSessionTitleRequest, + SetSessionTitleResponse, SseMcpServer, - StartNesRequest, - StartNesResponse, - SuggestNesRequest, - SuggestNesResponse, + SystemPrompt, TextContentBlock, - TextDocumentContentChangeEvent, - WorkspaceFolder, -) -from ..utils import ( - compatible_class, - notify_model, - param_model, - request_model, - request_model_from_dict, + UnarchiveSessionRequest, + UnarchiveSessionResponse, ) +from ..utils import compatible_class, notify_model, param_model, request_model, request_model_from_dict from .router import build_client_router __all__ = ["ClientSideConnection"] @@ -110,7 +100,6 @@ async def session_update(self, session_id: str, update: Any, **kwargs: Any) -> N pending = self._pending.setdefault(session_id, set()) pending.add(completed) token = self._current_update.set(completed) - try: if self._session_update is None: raise RequestError.method_not_found(CLIENT_METHODS["session_update"]) @@ -129,8 +118,6 @@ async def session_update(self, session_id: str, update: Any, **kwargs: Any) -> N self._pending.pop(session_id, None) async def wait(self, session_id: str) -> None: - # Snapshot before yielding so updates received after the response are - # not associated with this prompt. current = self._current_update.get() notifications = tuple( completed for completed in self._pending.get(session_id, set()) if completed is not current @@ -161,7 +148,6 @@ def __init__( client = to_client(self) if callable(to_client) else to_client self._session_updates = _SessionUpdateTracker(cast(Client, client)) handler = build_client_router(cast(Client, self._session_updates), use_unstable_protocol=use_unstable_protocol) - if isinstance(input_stream, Transport): if output_stream is not None: raise TypeError(_CLIENT_CONNECTION_ERROR) @@ -201,6 +187,8 @@ async def new_session( cwd: str, additional_directories: list[str] | None = None, mcp_servers: list[HttpMcpServer | SseMcpServer | AcpMcpServer | McpServerStdio] | None = None, + system_prompt: SystemPrompt | None = None, + config_options: list[InitialSessionConfigOption1 | InitialSessionConfigOption2] | None = None, **kwargs: Any, ) -> NewSessionResponse: resolved_mcp_servers = mcp_servers or [] @@ -211,6 +199,8 @@ async def new_session( cwd=cwd, additional_directories=additional_directories, mcp_servers=resolved_mcp_servers, + system_prompt=system_prompt, + config_options=config_options, field_meta=kwargs or None, ), NewSessionResponse, @@ -223,6 +213,8 @@ async def load_session( session_id: str, mcp_servers: list[HttpMcpServer | SseMcpServer | AcpMcpServer | McpServerStdio] | None = None, additional_directories: list[str] | None = None, + system_prompt: SystemPrompt | None = None, + config_options: list[InitialSessionConfigOption1 | InitialSessionConfigOption2] | None = None, **kwargs: Any, ) -> LoadSessionResponse: resolved_mcp_servers = mcp_servers or [] @@ -234,6 +226,8 @@ async def load_session( additional_directories=additional_directories, mcp_servers=resolved_mcp_servers, session_id=session_id, + system_prompt=system_prompt, + config_options=config_options, field_meta=kwargs or None, ), LoadSessionResponse, @@ -241,12 +235,16 @@ async def load_session( @param_model(ListSessionsRequest) async def list_sessions( - self, cwd: str | None = None, cursor: str | None = None, **kwargs: Any + self, + cwd: str | None = None, + cursor: str | None = None, + archived: Literal["exclude"] | Literal["include"] | Literal["only"] | str | None = None, + **kwargs: Any, ) -> ListSessionsResponse: return await request_model_from_dict( self._conn, AGENT_METHODS["session_list"], - ListSessionsRequest(cursor=cursor, cwd=cwd, field_meta=kwargs or None), + ListSessionsRequest(cursor=cursor, cwd=cwd, archived=archived, field_meta=kwargs or None), ListSessionsResponse, ) @@ -316,8 +314,11 @@ async def fork_session( self, session_id: str, cwd: str, + cursor_id: str | None = None, additional_directories: list[str] | None = None, mcp_servers: list[HttpMcpServer | SseMcpServer | AcpMcpServer | McpServerStdio] | None = None, + system_prompt: SystemPrompt | None = None, + config_options: list[InitialSessionConfigOption1 | InitialSessionConfigOption2] | None = None, **kwargs: Any, ) -> ForkSessionResponse: return await request_model( @@ -328,6 +329,9 @@ async def fork_session( cwd=cwd, additional_directories=additional_directories, mcp_servers=mcp_servers, + cursor_id=cursor_id, + system_prompt=system_prompt, + config_options=config_options, field_meta=kwargs or None, ), ForkSessionResponse, @@ -340,6 +344,8 @@ async def resume_session( cwd: str, additional_directories: list[str] | None = None, mcp_servers: list[HttpMcpServer | SseMcpServer | AcpMcpServer | McpServerStdio] | None = None, + system_prompt: SystemPrompt | None = None, + config_options: list[InitialSessionConfigOption1 | InitialSessionConfigOption2] | None = None, **kwargs: Any, ) -> ResumeSessionResponse: return await request_model( @@ -350,6 +356,8 @@ async def resume_session( cwd=cwd, additional_directories=additional_directories, mcp_servers=mcp_servers, + system_prompt=system_prompt, + config_options=config_options, field_meta=kwargs or None, ), ResumeSessionResponse, @@ -381,6 +389,64 @@ async def delete_session(self, session_id: str, **kwargs: Any) -> DeleteSessionR DeleteSessionResponse, ) + @param_model(ArchiveSessionRequest) + async def archive_session(self, session_id: str, **kwargs: Any) -> ArchiveSessionResponse: + return await request_model_from_dict( + self._conn, + AGENT_METHODS["session_archive"], + ArchiveSessionRequest(session_id=session_id, field_meta=kwargs or None), + ArchiveSessionResponse, + ) + + @param_model(UnarchiveSessionRequest) + async def unarchive_session(self, session_id: str, **kwargs: Any) -> UnarchiveSessionResponse: + return await request_model_from_dict( + self._conn, + AGENT_METHODS["session_unarchive"], + UnarchiveSessionRequest(session_id=session_id, field_meta=kwargs or None), + UnarchiveSessionResponse, + ) + + @param_model(SessionStatusRequest) + async def session_status(self, session_id: str, **kwargs: Any) -> SessionStatusResponse: + return await request_model( + self._conn, + AGENT_METHODS["session_status"], + SessionStatusRequest(session_id=session_id, field_meta=kwargs or None), + SessionStatusResponse, + ) + + @param_model(SessionOptionsRequest) + async def session_options( + self, cwd: str, additional_directories: list[str] | None = None, session_id: str | None = None, **kwargs: Any + ) -> SessionOptionsResponse: + return await request_model( + self._conn, + AGENT_METHODS["session_options"], + SessionOptionsRequest( + cwd=cwd, additional_directories=additional_directories, session_id=session_id, field_meta=kwargs or None + ), + SessionOptionsResponse, + ) + + @param_model(SetSessionTitleRequest) + async def set_session_title(self, session_id: str, title: str, **kwargs: Any) -> SetSessionTitleResponse: + return await request_model( + self._conn, + AGENT_METHODS["session_set_title"], + SetSessionTitleRequest(session_id=session_id, title=title, field_meta=kwargs or None), + SetSessionTitleResponse, + ) + + @param_model(AuthStatusRequest) + async def auth_status(self, **kwargs: Any) -> AuthStatusResponse: + return await request_model( + self._conn, + AGENT_METHODS["auth_status"], + AuthStatusRequest(field_meta=kwargs or None), + AuthStatusResponse, + ) + @param_model(ListProvidersRequest) async def list_providers(self, **kwargs: Any) -> ListProvidersResponse: return await request_model( @@ -444,156 +510,6 @@ async def notify_mcp( ), ) - @param_model(StartNesRequest) - async def start_nes( - self, - workspace_uri: str | None = None, - workspace_folders: list[WorkspaceFolder] | None = None, - repository: NesRepository | None = None, - **kwargs: Any, - ) -> StartNesResponse: - return await request_model( - self._conn, - AGENT_METHODS["nes_start"], - StartNesRequest( - workspace_uri=workspace_uri, - workspace_folders=workspace_folders, - repository=repository, - field_meta=kwargs or None, - ), - StartNesResponse, - ) - - @param_model(SuggestNesRequest) - async def suggest_nes( - self, - session_id: str, - uri: str, - version: int, - position: Position, - trigger_kind: Literal["automatic", "diagnostic", "manual"], - selection: Range | None = None, - context: NesSuggestContext | None = None, - **kwargs: Any, - ) -> SuggestNesResponse: - return await request_model( - self._conn, - AGENT_METHODS["nes_suggest"], - SuggestNesRequest( - session_id=session_id, - uri=uri, - version=version, - position=position, - selection=selection, - trigger_kind=trigger_kind, - context=context, - field_meta=kwargs or None, - ), - SuggestNesResponse, - ) - - @param_model(CloseNesRequest) - async def close_nes(self, session_id: str, **kwargs: Any) -> CloseNesResponse: - return await request_model_from_dict( - self._conn, - AGENT_METHODS["nes_close"], - CloseNesRequest(session_id=session_id, field_meta=kwargs or None), - CloseNesResponse, - ) - - @param_model(AcceptNesNotification) - async def accept_nes(self, session_id: str, id: str, **kwargs: Any) -> None: # noqa: A002 - await notify_model( - self._conn, - AGENT_METHODS["nes_accept"], - AcceptNesNotification(session_id=session_id, id=id, field_meta=kwargs or None), - ) - - @param_model(RejectNesNotification) - async def reject_nes( - self, - session_id: str, - id: str, # noqa: A002 - reason: Literal["rejected", "ignored", "replaced", "cancelled"] | None = None, - **kwargs: Any, - ) -> None: - await notify_model( - self._conn, - AGENT_METHODS["nes_reject"], - RejectNesNotification(session_id=session_id, id=id, reason=reason, field_meta=kwargs or None), - ) - - @param_model(DidOpenDocumentNotification) - async def did_open( - self, session_id: str, uri: str, language_id: str, version: int, text: str, **kwargs: Any - ) -> None: - await notify_model( - self._conn, - AGENT_METHODS["document_did_open"], - DidOpenDocumentNotification( - session_id=session_id, - uri=uri, - language_id=language_id, - version=version, - text=text, - field_meta=kwargs or None, - ), - ) - - @param_model(DidChangeDocumentNotification) - async def did_change( - self, - session_id: str, - uri: str, - version: int, - content_changes: list[TextDocumentContentChangeEvent], - **kwargs: Any, - ) -> None: - await notify_model( - self._conn, - AGENT_METHODS["document_did_change"], - DidChangeDocumentNotification( - session_id=session_id, - uri=uri, - version=version, - content_changes=content_changes, - field_meta=kwargs or None, - ), - ) - - @param_model(DidCloseDocumentNotification) - async def did_close(self, session_id: str, uri: str, **kwargs: Any) -> None: - await notify_model( - self._conn, - AGENT_METHODS["document_did_close"], - DidCloseDocumentNotification(session_id=session_id, uri=uri, field_meta=kwargs or None), - ) - - @param_model(DidSaveDocumentNotification) - async def did_save(self, session_id: str, uri: str, **kwargs: Any) -> None: - await notify_model( - self._conn, - AGENT_METHODS["document_did_save"], - DidSaveDocumentNotification(session_id=session_id, uri=uri, field_meta=kwargs or None), - ) - - @param_model(DidFocusDocumentNotification) - async def did_focus( - self, session_id: str, uri: str, version: int, position: Position, visible_range: Range, **kwargs: Any - ) -> None: - await notify_model( - self._conn, - AGENT_METHODS["document_did_focus"], - DidFocusDocumentNotification( - session_id=session_id, - uri=uri, - version=version, - position=position, - visible_range=visible_range, - field_meta=kwargs or None, - ), - ) - async def ext_method(self, method: str, params: dict[str, Any]) -> dict[str, Any]: return await self._conn.send_request(f"_{method}", params) diff --git a/src/acp/experimental/v2/schema.py b/src/acp/experimental/v2/schema.py index 801771be..5310eb49 100644 --- a/src/acp/experimental/v2/schema.py +++ b/src/acp/experimental/v2/schema.py @@ -5589,10 +5589,12 @@ class ClientResponseMessage(BaseModel): """ result: Union[ RequestPermissionResponse, - Union[ - AcceptElicitationResponse, DeclineElicitationResponse, CancelElicitationResponse, OtherElicitationResponse - ], - Union[McpResultResponse, McpErrorResponse], + AcceptElicitationResponse, + DeclineElicitationResponse, + CancelElicitationResponse, + OtherElicitationResponse, + McpResultResponse, + McpErrorResponse, Any, ] """ @@ -5907,11 +5909,9 @@ class ClientRequest(BaseModel): StartNesRequest, SuggestNesRequest, CloseNesRequest, - Union[ - SetSessionConfigOptionIdRequest, - SetSessionConfigOptionBooleanRequest, - SetSessionConfigOptionOtherRequest, - ], + SetSessionConfigOptionIdRequest, + SetSessionConfigOptionBooleanRequest, + SetSessionConfigOptionOtherRequest, Any, ] ] = None @@ -6017,13 +6017,11 @@ class UpdateSessionNotification(BaseModel): SessionMessageUpdate, SessionMessageChunkUpdate, OtherSessionUpdate, - Union[ - RunningSessionStateUpdate, - IdleSessionStateUpdate, - RequiresActionSessionStateUpdate, - UnknownSessionStateUpdate, - OtherSessionStateUpdate, - ], + RunningSessionStateUpdate, + IdleSessionStateUpdate, + RequiresActionSessionStateUpdate, + UnknownSessionStateUpdate, + OtherSessionStateUpdate, ] """ The actual update content. @@ -6156,11 +6154,12 @@ class AgentRequest(BaseModel): Union[ RequestPermissionRequest, MessageMcpRequest, - Union[ - Union[CreateOtherSessionElicitationRequest, CreateOtherRequestElicitationRequest], - Union[CreateFormSessionElicitationRequest, CreateFormRequestElicitationRequest], - Union[CreateUrlSessionElicitationRequest, CreateUrlRequestElicitationRequest], - ], + CreateOtherSessionElicitationRequest, + CreateOtherRequestElicitationRequest, + CreateFormSessionElicitationRequest, + CreateFormRequestElicitationRequest, + CreateUrlSessionElicitationRequest, + CreateUrlRequestElicitationRequest, Any, ] ] = None diff --git a/src/acp/interfaces.py b/src/acp/interfaces.py index d4641f9b..4f399796 100644 --- a/src/acp/interfaces.py +++ b/src/acp/interfaces.py @@ -13,21 +13,24 @@ ) from .meta import AGENT_METHODS, CLIENT_METHODS from .schema import ( - AcceptNesNotification, AcpMcpServer, AgentMessageChunk, AgentPlanContentUpdate, AgentPlanRemovedUpdate, AgentPlanUpdate, AgentThoughtChunk, + ArchiveSessionRequest, + ArchiveSessionResponse, AudioContentBlock, + AuthAccount, AuthenticateRequest, AuthenticateResponse, + AuthStatusRequest, + AuthStatusResponse, + AuthStatusUpdateNotification, AvailableCommandsUpdate, CancelNotification, ClientCapabilities, - CloseNesRequest, - CloseNesResponse, CloseSessionRequest, CloseSessionResponse, CompleteElicitationNotification, @@ -42,11 +45,6 @@ CurrentModeUpdate, DeleteSessionRequest, DeleteSessionResponse, - DidChangeDocumentNotification, - DidCloseDocumentNotification, - DidFocusDocumentNotification, - DidOpenDocumentNotification, - DidSaveDocumentNotification, DisableProviderRequest, DisableProviderResponse, ElicitationMode, @@ -59,6 +57,8 @@ Implementation, InitializeRequest, InitializeResponse, + InitialSessionConfigOption1, + InitialSessionConfigOption2, KillTerminalRequest, KillTerminalResponse, ListProvidersRequest, @@ -73,18 +73,13 @@ MessageMcpNotification, MessageMcpRequest, MessageMcpResponse, - NesRepository, - NesSuggestContext, NewSessionRequest, NewSessionResponse, PermissionOption, - Position, PromptRequest, PromptResponse, - Range, ReadTextFileRequest, ReadTextFileResponse, - RejectNesNotification, ReleaseTerminalRequest, ReleaseTerminalResponse, RequestPermissionRequest, @@ -94,9 +89,15 @@ ResumeSessionResponse, SessionInfoUpdate, SessionNotification, + SessionOptionsRequest, + SessionOptionsResponse, + SessionStatusRequest, + SessionStatusResponse, SessionUpdateCompactionSummaryChunk, SessionUpdateCompactionUpdate, + SessionUpdateCursorUpdate, SessionUpdateNotice, + SessionUpdatePromptSuggestionsUpdate, SessionUpdateSessionMessage, SessionUpdateSessionMessageChunk, SessionUpdateSubagentUpdate, @@ -107,23 +108,22 @@ SetSessionConfigOptionSelectRequest, SetSessionModeRequest, SetSessionModeResponse, + SetSessionTitleRequest, + SetSessionTitleResponse, SseMcpServer, - StartNesRequest, - StartNesResponse, - SuggestNesRequest, - SuggestNesResponse, + SystemPrompt, TerminalOutputRequest, TerminalOutputResponse, TextContentBlock, - TextDocumentContentChangeEvent, ToolCallProgress, ToolCallStart, ToolCallUpdate, + UnarchiveSessionRequest, + UnarchiveSessionResponse, UsageUpdate, UserMessageChunk, WaitForTerminalExitRequest, WaitForTerminalExitResponse, - WorkspaceFolder, WriteTextFileRequest, WriteTextFileResponse, ) @@ -168,6 +168,8 @@ async def session_update( | SessionUpdateNotice | SessionUpdateCompactionUpdate | SessionUpdateCompactionSummaryChunk + | SessionUpdatePromptSuggestionsUpdate + | SessionUpdateCursorUpdate | SessionUpdateSubagentUpdate | SessionUpdateSessionMessage | SessionUpdateSessionMessageChunk, @@ -249,6 +251,13 @@ async def create_elicitation( ) async def complete_elicitation(self, elicitation_id: str, **kwargs: Any) -> None: ... + @param_model( + AuthStatusUpdateNotification, method=CLIENT_METHODS["auth_status_update"], kind="notification", unstable=True + ) + async def auth_status_update( + self, state: str, accounts: list[AuthAccount] | None = None, **kwargs: Any + ) -> None: ... + async def ext_method(self, method: str, params: dict[str, Any]) -> dict[str, Any]: ... async def ext_notification(self, method: str, params: dict[str, Any]) -> None: ... @@ -260,6 +269,30 @@ class Agent(Protocol): @param_model(DeleteSessionRequest, method=AGENT_METHODS["session_delete"], adapt_result=normalize_result) async def delete_session(self, session_id: str, **kwargs: Any) -> DeleteSessionResponse: ... + @param_model( + ArchiveSessionRequest, method=AGENT_METHODS["session_archive"], unstable=True, adapt_result=normalize_result + ) + async def archive_session(self, session_id: str, **kwargs: Any) -> ArchiveSessionResponse: ... + + @param_model( + UnarchiveSessionRequest, method=AGENT_METHODS["session_unarchive"], unstable=True, adapt_result=normalize_result + ) + async def unarchive_session(self, session_id: str, **kwargs: Any) -> UnarchiveSessionResponse: ... + + @param_model(SessionStatusRequest, method=AGENT_METHODS["session_status"], unstable=True) + async def session_status(self, session_id: str, **kwargs: Any) -> SessionStatusResponse: ... + + @param_model(SessionOptionsRequest, method=AGENT_METHODS["session_options"], unstable=True) + async def session_options( + self, cwd: str, additional_directories: list[str] | None = None, session_id: str | None = None, **kwargs: Any + ) -> SessionOptionsResponse: ... + + @param_model(SetSessionTitleRequest, method=AGENT_METHODS["session_set_title"], unstable=True) + async def set_session_title(self, session_id: str, title: str, **kwargs: Any) -> SetSessionTitleResponse: ... + + @param_model(AuthStatusRequest, method=AGENT_METHODS["auth_status"], unstable=True) + async def auth_status(self, **kwargs: Any) -> AuthStatusResponse: ... + @param_model(ListProvidersRequest, method=AGENT_METHODS["providers_list"], unstable=True) async def list_providers(self, **kwargs: Any) -> ListProvidersResponse: ... @@ -293,79 +326,6 @@ async def notify_mcp( self, server_id: str, request_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any ) -> None: ... - @param_model(StartNesRequest, method=AGENT_METHODS["nes_start"], unstable=True) - async def start_nes( - self, - workspace_uri: str | None = None, - workspace_folders: list[WorkspaceFolder] | None = None, - repository: NesRepository | None = None, - **kwargs: Any, - ) -> StartNesResponse: ... - - @param_model(SuggestNesRequest, method=AGENT_METHODS["nes_suggest"], unstable=True) - async def suggest_nes( - self, - session_id: str, - uri: str, - version: int, - position: Position, - trigger_kind: Literal["automatic", "diagnostic", "manual"], - selection: Range | None = None, - context: NesSuggestContext | None = None, - **kwargs: Any, - ) -> SuggestNesResponse: ... - - @param_model(CloseNesRequest, method=AGENT_METHODS["nes_close"], unstable=True, adapt_result=normalize_result) - async def close_nes(self, session_id: str, **kwargs: Any) -> CloseNesResponse: ... - - @param_model(AcceptNesNotification, method=AGENT_METHODS["nes_accept"], kind="notification", unstable=True) - async def accept_nes(self, session_id: str, id: str, **kwargs: Any) -> None: ... # noqa: A002 - - @param_model(RejectNesNotification, method=AGENT_METHODS["nes_reject"], kind="notification", unstable=True) - async def reject_nes( - self, - session_id: str, - id: str, # noqa: A002 - reason: Literal["rejected", "ignored", "replaced", "cancelled"] | None = None, - **kwargs: Any, - ) -> None: ... - - @param_model( - DidOpenDocumentNotification, method=AGENT_METHODS["document_did_open"], kind="notification", unstable=True - ) - async def did_open( - self, session_id: str, uri: str, language_id: str, version: int, text: str, **kwargs: Any - ) -> None: ... - - @param_model( - DidChangeDocumentNotification, method=AGENT_METHODS["document_did_change"], kind="notification", unstable=True - ) - async def did_change( - self, - session_id: str, - uri: str, - version: int, - content_changes: list[TextDocumentContentChangeEvent], - **kwargs: Any, - ) -> None: ... - - @param_model( - DidCloseDocumentNotification, method=AGENT_METHODS["document_did_close"], kind="notification", unstable=True - ) - async def did_close(self, session_id: str, uri: str, **kwargs: Any) -> None: ... - - @param_model( - DidSaveDocumentNotification, method=AGENT_METHODS["document_did_save"], kind="notification", unstable=True - ) - async def did_save(self, session_id: str, uri: str, **kwargs: Any) -> None: ... - - @param_model( - DidFocusDocumentNotification, method=AGENT_METHODS["document_did_focus"], kind="notification", unstable=True - ) - async def did_focus( - self, session_id: str, uri: str, version: int, position: Position, visible_range: Range, **kwargs: Any - ) -> None: ... - @param_model(InitializeRequest, method=AGENT_METHODS["initialize"]) async def initialize( self, @@ -381,6 +341,8 @@ async def new_session( cwd: str, additional_directories: list[str] | None = None, mcp_servers: list[HttpMcpServer | SseMcpServer | AcpMcpServer | McpServerStdio] | None = None, + system_prompt: SystemPrompt | None = None, + config_options: list[InitialSessionConfigOption1 | InitialSessionConfigOption2] | None = None, **kwargs: Any, ) -> NewSessionResponse: ... @@ -391,12 +353,18 @@ async def load_session( session_id: str, mcp_servers: list[HttpMcpServer | SseMcpServer | AcpMcpServer | McpServerStdio] | None = None, additional_directories: list[str] | None = None, + system_prompt: SystemPrompt | None = None, + config_options: list[InitialSessionConfigOption1 | InitialSessionConfigOption2] | None = None, **kwargs: Any, ) -> LoadSessionResponse | None: ... @param_model(ListSessionsRequest, method=AGENT_METHODS["session_list"]) async def list_sessions( - self, cwd: str | None = None, cursor: str | None = None, **kwargs: Any + self, + cwd: str | None = None, + cursor: str | None = None, + archived: Literal["exclude"] | Literal["include"] | Literal["only"] | str | None = None, + **kwargs: Any, ) -> ListSessionsResponse: ... @param_model(SetSessionModeRequest, method=AGENT_METHODS["session_set_mode"], adapt_result=normalize_result) @@ -434,8 +402,11 @@ async def fork_session( self, session_id: str, cwd: str, + cursor_id: str | None = None, additional_directories: list[str] | None = None, mcp_servers: list[HttpMcpServer | SseMcpServer | AcpMcpServer | McpServerStdio] | None = None, + system_prompt: SystemPrompt | None = None, + config_options: list[InitialSessionConfigOption1 | InitialSessionConfigOption2] | None = None, **kwargs: Any, ) -> ForkSessionResponse: ... @@ -446,6 +417,8 @@ async def resume_session( cwd: str, additional_directories: list[str] | None = None, mcp_servers: list[HttpMcpServer | SseMcpServer | AcpMcpServer | McpServerStdio] | None = None, + system_prompt: SystemPrompt | None = None, + config_options: list[InitialSessionConfigOption1 | InitialSessionConfigOption2] | None = None, **kwargs: Any, ) -> ResumeSessionResponse: ... diff --git a/src/acp/meta.py b/src/acp/meta.py index 9960944a..1c72890e 100644 --- a/src/acp/meta.py +++ b/src/acp/meta.py @@ -1,5 +1,5 @@ # Generated from schema/meta.json. Do not edit by hand. -# Schema ref: refs/tags/schema-v1.24.1 +# Schema ref: refs/tags/schema-v1.33.0 AGENT_METHODS = { "initialize": "initialize", "authenticate": "authenticate", @@ -16,19 +16,15 @@ "session_list": "session/list", "session_delete": "session/delete", "session_fork": "session/fork", + "session_archive": "session/archive", + "session_unarchive": "session/unarchive", + "session_status": "session/status", + "session_options": "session/options", + "session_set_title": "session/set_title", "session_resume": "session/resume", "session_close": "session/close", "logout": "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", + "auth_status": "auth/status", } CLIENT_METHODS = { "session_request_permission": "session/request_permission", @@ -43,6 +39,7 @@ "mcp_message": "mcp/message", "elicitation_create": "elicitation/create", "elicitation_complete": "elicitation/complete", + "auth_status_update": "auth/status_update", } PROTOCOL_METHODS = {"cancel_request": "$/cancel_request"} PROTOCOL_VERSION = 1 diff --git a/src/acp/schema.py b/src/acp/schema.py index 9ee274f5..5b31cce7 100644 --- a/src/acp/schema.py +++ b/src/acp/schema.py @@ -1,5 +1,5 @@ # Generated from schema/schema.json. Do not edit by hand. -# Schema ref: refs/tags/schema-v1.24.1 +# Schema ref: refs/tags/schema-v1.33.0 from __future__ import annotations @@ -43,14 +43,9 @@ class ReadTextFileRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - @field_validator("limit", "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 TextResourceContents(BaseModel): mime_type: Annotated[Optional[str], Field(alias="mimeType")] = None @@ -71,7 +66,7 @@ class TextResourceContents(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("mime_type", mode="wrap") @@ -99,7 +94,7 @@ class BlobResourceContents(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("mime_type", mode="wrap") @@ -115,7 +110,7 @@ class Diff(BaseModel): """ old_text: Annotated[Optional[str], Field(alias="oldText")] = None """ - The original content (None for new files). + The original content (omitted or `null` for new files). """ new_text: Annotated[str, Field(alias="newText")] """ @@ -127,7 +122,7 @@ class Diff(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("old_text", mode="wrap") @@ -147,7 +142,22 @@ class Terminal(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + """ + + +class SessionReference(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The referenced 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/v1/draft/extensibility) """ @@ -158,7 +168,7 @@ class ToolCallLocation(BaseModel): """ line: Annotated[Optional[int], Field(ge=0)] = None """ - Optional line number within the file. + Optional 1-based line number within the file. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -166,7 +176,7 @@ class ToolCallLocation(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("line", mode="wrap") @@ -190,7 +200,7 @@ class EnvVariable(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -209,7 +219,7 @@ class TerminalOutputRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -228,7 +238,7 @@ class ReleaseTerminalRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -247,7 +257,7 @@ class WaitForTerminalExitRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -266,7 +276,7 @@ class KillTerminalRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -283,7 +293,7 @@ class CreateFormElicitationRequestBase(BaseModel): Optional. Omitted and `null` are equivalent and mean no metadata. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ mode: Literal["form"] = "form" @@ -301,7 +311,7 @@ class CreateUrlElicitationRequestBase(BaseModel): Optional. Omitted and `null` are equivalent and mean no metadata. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ mode: Literal["url"] = "url" @@ -369,7 +379,7 @@ class EnumOption(BaseModel): Optional. Omitted and `null` are equivalent and mean no metadata. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("description", mode="wrap") @@ -441,7 +451,7 @@ class StringPropertySchema(BaseModel): Optional. Omitted and `null` are equivalent and mean no metadata. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("default", "description", "title", mode="wrap") @@ -489,7 +499,7 @@ class NumberPropertySchema(BaseModel): Optional. Omitted and `null` are equivalent and mean no metadata. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("default", "description", "title", mode="wrap") @@ -537,7 +547,7 @@ class IntegerPropertySchema(BaseModel): Optional. Omitted and `null` are equivalent and mean no metadata. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("default", "description", "title", mode="wrap") @@ -573,7 +583,7 @@ class BooleanPropertySchema(BaseModel): Optional. Omitted and `null` are equivalent and mean no metadata. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("default", "description", "title", mode="wrap") @@ -609,7 +619,7 @@ class StringMultiSelectItemsBase(BaseModel): Optional. Omitted and `null` are equivalent and mean no metadata. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -626,7 +636,7 @@ class TitledMultiSelectItems(BaseModel): Optional. Omitted and `null` are equivalent and mean no metadata. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -662,17 +672,17 @@ class ElicitationUrlMode(RootModel[Union[ElicitationUrlSessionMode, ElicitationU class PromptCapabilities(BaseModel): image: Optional[bool] = False """ - Agent supports [`ContentBlock::Image`]. + Agent supports `image` content blocks. """ audio: Optional[bool] = False """ - Agent supports [`ContentBlock::Audio`]. + Agent supports `audio` content blocks. """ embedded_context: Annotated[Optional[bool], Field(alias="embeddedContext")] = False """ Agent supports embedded context in `session/prompt` requests. - When enabled, the Client is allowed to include [`ContentBlock::Resource`] + When enabled, the Client is allowed to include `resource` content blocks in prompt requests for pieces of context that are referenced in the message. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None @@ -681,7 +691,7 @@ class PromptCapabilities(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("audio", "embedded_context", "image", mode="wrap") @@ -693,11 +703,11 @@ def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHa class McpCapabilities(BaseModel): http: Optional[bool] = False """ - Agent supports [`McpServer::Http`]. + Agent supports `http` MCP servers. """ sse: Optional[bool] = False """ - Agent supports [`McpServer::Sse`]. + Agent supports `sse` MCP servers. """ acp: Optional[bool] = False """ @@ -705,7 +715,7 @@ class McpCapabilities(BaseModel): This capability is not part of the spec yet, and may be removed or changed at any point. - Agent supports [`McpServer::Acp`]. + Agent supports `acp` MCP servers. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -713,7 +723,7 @@ class McpCapabilities(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("acp", "http", "sse", mode="wrap") @@ -729,7 +739,7 @@ class SessionListCapabilities(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -740,7 +750,7 @@ class SessionDeleteCapabilities(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -751,199 +761,128 @@ class SessionAdditionalDirectoriesCapabilities(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/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/extensibility) - """ - - -class SessionResumeCapabilities(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/extensibility) - """ - - -class SessionCloseCapabilities(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/extensibility) - """ - - -class LogoutCapabilities(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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class ProvidersCapabilities(BaseModel): +class SessionSystemPromptOverrideCapabilities(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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class NesDocumentDidOpenCapabilities(BaseModel): +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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class NesDocumentDidCloseCapabilities(BaseModel): +class SessionArchiveCapabilities(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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class NesDocumentDidSaveCapabilities(BaseModel): +class SessionStatusCapabilities(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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class NesDocumentDidFocusCapabilities(BaseModel): +class SessionOptionsCapabilities(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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/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. - """ +class SessionTitleCapabilities(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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/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): +class SessionResumeCapabilities(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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/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. - """ +class SessionCloseCapabilities(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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/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. - """ +class AuthStatusCapabilities(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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/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): +class LogoutCapabilities(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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class NesDiagnosticsCapabilities(BaseModel): +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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -958,7 +897,7 @@ class AuthMethodTerminal(BaseModel): """ description: Optional[str] = None """ - Optional description providing more details about this authentication method. + Optional human-readable description of this authentication method. """ args: Optional[List[str]] = None """ @@ -975,19 +914,14 @@ class AuthMethodTerminal(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - @field_validator("description", "env", mode="wrap") + @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", 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): id: str @@ -1000,7 +934,7 @@ class AuthMethodAgent(BaseModel): """ description: Optional[str] = None """ - Optional description providing more details about this authentication method. + Optional human-readable description of this authentication method. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -1008,7 +942,7 @@ class AuthMethodAgent(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("description", mode="wrap") @@ -1021,11 +955,11 @@ 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. + name fallback if title isn't present. """ title: Optional[str] = None """ - Intended for UI and end-user contexts — optimized to be human-readable + Intended for UI and end-user contexts and optimized to be human-readable and easily understood. If not provided, the name should be used for display. @@ -1041,7 +975,7 @@ class Implementation(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("title", mode="wrap") @@ -1057,7 +991,7 @@ class AuthenticateResponse(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -1079,7 +1013,7 @@ class ProviderCurrentConfig(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -1090,7 +1024,7 @@ class SetProviderResponse(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -1101,7 +1035,7 @@ class DisableProviderResponse(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -1112,9 +1046,63 @@ class LogoutResponse(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + """ + + +class AuthAccount(BaseModel): + label: str + """ + Human-readable name for the account, suitable for display on its own, + for example `Claude Max`, `OpenAI API key`, or `Vertex AI`. + """ + description: Optional[str] = None + """ + Short text shown with the label, such as the credential source, for example + `API key helper`. MUST NOT contain credentials. + + Optional. Omitted and `null` are equivalent and mean no description is reported. + """ + active: Optional[bool] = None + """ + Whether the agent currently uses this account by default. + + Several accounts MAY be active, for example one per provider. + + Optional. Omitted and `null` are equivalent and mean the agent does not indicate whether this account is in effect. + """ + name: Optional[str] = None + """ + Display name of the user, such as a username or full name. + + Optional. Omitted and `null` are equivalent and mean no name is reported. + """ + email: Optional[str] = None + """ + Email address of the user. + + Optional. Omitted and `null` are equivalent and mean no email is reported. + """ + organization: Optional[str] = None + """ + Display name of the organization, team, or workspace the account is using. + + Optional. Omitted and `null` are equivalent and mean no organization is reported. + """ + 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/v1/draft/extensibility) """ + @field_validator("active", "description", "email", "name", "organization", 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 SessionMode(BaseModel): id: str @@ -1135,7 +1123,7 @@ class SessionMode(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("description", mode="wrap") @@ -1163,7 +1151,7 @@ class SessionConfigSelectOption(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("description", mode="wrap") @@ -1204,16 +1192,27 @@ class SessionInfo(BaseModel): """ ISO 8601 timestamp of last activity """ + archived: Optional[bool] = None + """ + **UNSTABLE** + + This capability is not part of the spec yet, and may be removed or changed at any point. + + Whether the session is archived. + + Optional. Omitted and `null` are equivalent and mean the archive state is not reported. + Agents that advertise the `sessionCapabilities.archive` capability MUST include it on every listed 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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - @field_validator("title", "updated_at", mode="wrap") + @field_validator("archived", "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) @@ -1231,95 +1230,39 @@ class DeleteSessionResponse(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class SetSessionModeResponse(BaseModel): +class ArchiveSessionResponse(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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/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 across all turns. - """ - output_tokens: Annotated[int, Field(alias="outputTokens", ge=0)] - """ - Total output tokens across all turns. - """ - 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. - """ +class UnarchiveSessionResponse(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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/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 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/extensibility) +class SetSessionTitleResponse(BaseModel): + title: str """ + The title the Agent stored. - -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). + This differs from the requested title if the Agent normalized it. Clients SHOULD + display this value rather than the one they sent. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -1327,119 +1270,70 @@ class Position(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class NesJumpSuggestion(BaseModel): - id: str - """ - Unique identifier for accept/reject tracking. - """ - uri: str - """ - The file to navigate to. - """ - position: Position - """ - The target position within the file. - """ +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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class NesRenameSuggestion(BaseModel): - id: str - """ - Unique identifier for accept/reject tracking. - """ - uri: str - """ - 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. - """ +class SetSessionModeResponse(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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class NesSearchAndReplaceSuggestion(BaseModel): - id: str +class Usage(BaseModel): + total_tokens: Annotated[int, Field(alias="totalTokens", ge=0)] """ - Unique identifier for accept/reject tracking. + Sum of all token types across session. """ - uri: str + input_tokens: Annotated[int, Field(alias="inputTokens", ge=0)] """ - The file URI to search within. + Total input tokens across all turns. """ - search: str + output_tokens: Annotated[int, Field(alias="outputTokens", ge=0)] """ - The text or pattern to find. + Total output tokens across all turns. """ - replace: str + thought_tokens: Annotated[Optional[int], Field(alias="thoughtTokens", ge=0)] = None """ - The replacement text. + Total thought/reasoning tokens """ - is_regex: Annotated[Optional[bool], Field(alias="isRegex")] = None + cached_read_tokens: Annotated[Optional[int], Field(alias="cachedReadTokens", ge=0)] = None """ - Whether `search` is a regular expression. Defaults to `false`. + Total cache read tokens. """ - field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + cached_write_tokens: Annotated[Optional[int], Field(alias="cachedWriteTokens", ge=0)] = None """ - The _meta property is reserved by ACP to allow clients and agents to attach additional - metadata to their interactions. Implementations MUST NOT make assumptions about values at - these keys. - - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + Total cache write tokens. """ - - -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/extensibility) - """ - - -class PlanFile(BaseModel): - plan_id: Annotated[str, Field(alias="planId")] - """ - The plan ID to update. - """ - uri: str - """ - The URI of the file containing the plan. + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - 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/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 PlanMarkdown(BaseModel): @@ -1451,15 +1345,28 @@ class PlanMarkdown(BaseModel): """ Markdown content for the plan. """ + path: Optional[str] = None + """ + The absolute path of the file that holds this plan. + + This field is optional. Omitting it or sending `null` both mean that the plan + has no file. `content` is the plan to display whether or not `path` is set. + Clients can use `path` to open 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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ + @field_validator("path", 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 PlanRemoved(BaseModel): plan_id: Annotated[str, Field(alias="planId")] @@ -1472,7 +1379,7 @@ class PlanRemoved(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -1487,7 +1394,7 @@ class UnstructuredCommandInput(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -1502,7 +1409,7 @@ class CurrentModeUpdateBase(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -1521,7 +1428,7 @@ class SessionInfoUpdateBase(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -1532,7 +1439,8 @@ class Cost(BaseModel): """ currency: str """ - ISO 4217 currency code (e.g., "USD", "EUR"). + Unit of `amount`: an ISO 4217 currency code (e.g., "USD", "EUR") for money, or another + unit such as "credits". """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -1540,7 +1448,7 @@ class Cost(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -1563,7 +1471,7 @@ class UsageUpdateBase(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -1595,24 +1503,298 @@ def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHa return use_default_on_error(v, handler, info) -class SessionCancelCapabilities(BaseModel): +class CursorForkCapabilities(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. + metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. + Implementations MUST NOT assign meaning to keys they do not recognize. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class StateUpdate5(BaseModel): +class CursorAnchor7(BaseModel): model_config = ConfigDict( extra="allow", ) - state: str + type: str """ - Unrecognized state discriminator. + Custom or future anchor type. + + Values beginning with `_` are reserved for implementation-specific + extensions. Unknown values that do not begin with `_` are reserved for + future ACP variants. + """ + + +class CursorMessageAnchor(BaseModel): + message_id: Annotated[str, Field(alias="messageId")] + """ + The ID of the anchored message. + """ + position: Union[Literal["before"], Literal["after"], str] + """ + On which side of the message the cursor is. + """ + 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 and `null` are equivalent and mean no metadata. + Implementations MUST NOT assign meaning to keys they do not recognize. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + """ + + +class CursorToolCallAnchor(BaseModel): + tool_call_id: Annotated[str, Field(alias="toolCallId")] + """ + The ID of the anchored tool call. + """ + position: Union[Literal["before"], Literal["after"], str] + """ + On which side of the tool call the cursor is. + """ + 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 and `null` are equivalent and mean no metadata. + Implementations MUST NOT assign meaning to keys they do not recognize. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + """ + + +class CursorCompactionAnchor(BaseModel): + compaction_id: Annotated[str, Field(alias="compactionId")] + """ + The ID of the anchored compaction. + """ + position: Union[Literal["before"], Literal["after"], str] + """ + On which side of the compaction the cursor is. + """ + 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 and `null` are equivalent and mean no metadata. + Implementations MUST NOT assign meaning to keys they do not recognize. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + """ + + +class SessionCancelCapabilities(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/v1/draft/extensibility) + """ + + +class StateUpdate21(BaseModel): + usage: Optional[Usage] = None + """ + **UNSTABLE** Token usage for completed foreground work. + + Optional. Omitted or `null` means not reported. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + The _meta property is reserved by ACP for additional metadata. + Implementations MUST NOT make assumptions about values at these keys. + Optional. Omitted and `null` mean no metadata for this state snapshot. + """ + stop_reason: Annotated[Literal["end_turn"], Field(alias="stopReason")] = "end_turn" + """ + Why foreground work stopped. The value selects one of this type's variants, which may add fields of their own. + + Optional. Omitted or `null` both mean the agent is not reporting a stop reason; a malformed value is treated the same way. + + See protocol docs: [Work state](https://agentclientprotocol.com/protocol/v1/draft/subagents#work-state) + """ + + +class StateUpdate22(BaseModel): + usage: Optional[Usage] = None + """ + **UNSTABLE** Token usage for completed foreground work. + + Optional. Omitted or `null` means not reported. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + The _meta property is reserved by ACP for additional metadata. + Implementations MUST NOT make assumptions about values at these keys. + Optional. Omitted and `null` mean no metadata for this state snapshot. + """ + stop_reason: Annotated[Literal["max_tokens"], Field(alias="stopReason")] = "max_tokens" + """ + Why foreground work stopped. The value selects one of this type's variants, which may add fields of their own. + + Optional. Omitted or `null` both mean the agent is not reporting a stop reason; a malformed value is treated the same way. + + See protocol docs: [Work state](https://agentclientprotocol.com/protocol/v1/draft/subagents#work-state) + """ + + +class StateUpdate23(BaseModel): + usage: Optional[Usage] = None + """ + **UNSTABLE** Token usage for completed foreground work. + + Optional. Omitted or `null` means not reported. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + The _meta property is reserved by ACP for additional metadata. + Implementations MUST NOT make assumptions about values at these keys. + Optional. Omitted and `null` mean no metadata for this state snapshot. + """ + stop_reason: Annotated[Literal["max_turn_requests"], Field(alias="stopReason")] = "max_turn_requests" + """ + Why foreground work stopped. The value selects one of this type's variants, which may add fields of their own. + + Optional. Omitted or `null` both mean the agent is not reporting a stop reason; a malformed value is treated the same way. + + See protocol docs: [Work state](https://agentclientprotocol.com/protocol/v1/draft/subagents#work-state) + """ + + +class StateUpdate24(BaseModel): + usage: Optional[Usage] = None + """ + **UNSTABLE** Token usage for completed foreground work. + + Optional. Omitted or `null` means not reported. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + The _meta property is reserved by ACP for additional metadata. + Implementations MUST NOT make assumptions about values at these keys. + Optional. Omitted and `null` mean no metadata for this state snapshot. + """ + stop_reason: Annotated[Literal["refusal"], Field(alias="stopReason")] = "refusal" + """ + Why foreground work stopped. The value selects one of this type's variants, which may add fields of their own. + + Optional. Omitted or `null` both mean the agent is not reporting a stop reason; a malformed value is treated the same way. + + See protocol docs: [Work state](https://agentclientprotocol.com/protocol/v1/draft/subagents#work-state) + """ + + +class StateUpdate25(BaseModel): + usage: Optional[Usage] = None + """ + **UNSTABLE** Token usage for completed foreground work. + + Optional. Omitted or `null` means not reported. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + The _meta property is reserved by ACP for additional metadata. + Implementations MUST NOT make assumptions about values at these keys. + Optional. Omitted and `null` mean no metadata for this state snapshot. + """ + stop_reason: Annotated[Literal["cancelled"], Field(alias="stopReason")] = "cancelled" + """ + Why foreground work stopped. The value selects one of this type's variants, which may add fields of their own. + + Optional. Omitted or `null` both mean the agent is not reporting a stop reason; a malformed value is treated the same way. + + See protocol docs: [Work state](https://agentclientprotocol.com/protocol/v1/draft/subagents#work-state) + """ + + +class StateUpdate27(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + usage: Optional[Usage] = None + """ + **UNSTABLE** Token usage for completed foreground work. + + Optional. Omitted or `null` means not reported. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + The _meta property is reserved by ACP for additional metadata. + Implementations MUST NOT make assumptions about values at these keys. + Optional. Omitted and `null` mean no metadata for this state snapshot. + """ + stop_reason: Annotated[str, Field(alias="stopReason")] + """ + Unrecognized stop reason. + """ + + +class StateUpdate28(BaseModel): + usage: Optional[Usage] = None + """ + **UNSTABLE** Token usage for completed foreground work. + + Optional. Omitted or `null` means not reported. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + The _meta property is reserved by ACP for additional metadata. + Implementations MUST NOT make assumptions about values at these keys. + Optional. Omitted and `null` mean no metadata for this state snapshot. + """ + stop_reason: Annotated[None, Field(alias="stopReason")] = None + """ + Why foreground work stopped. The value selects one of this type's variants, which may add fields of their own. + + Optional. Omitted or `null` both mean the agent is not reporting a stop reason; a malformed value is treated the same way. + + See protocol docs: [Work state](https://agentclientprotocol.com/protocol/v1/draft/subagents#work-state) + """ + + +class StateUpdate29(BaseModel): + state: Literal["idle"] = "idle" + + +class StateUpdate210(StateUpdate21, StateUpdate29): + state: Literal["idle"] = "idle" + + +class StateUpdate211(StateUpdate22, StateUpdate29): + state: Literal["idle"] = "idle" + + +class StateUpdate212(StateUpdate23, StateUpdate29): + state: Literal["idle"] = "idle" + + +class StateUpdate213(StateUpdate24, StateUpdate29): + state: Literal["idle"] = "idle" + + +class StateUpdate214(StateUpdate25, StateUpdate29): + state: Literal["idle"] = "idle" + + +class StateUpdate216(StateUpdate27, StateUpdate29): + state: Literal["idle"] = "idle" + + +class StateUpdate217(StateUpdate28, StateUpdate29): + state: Literal["idle"] = "idle" + + +class StateUpdate5(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + state: str + """ + Unrecognized state discriminator. """ @@ -1621,35 +1803,168 @@ class RunningStateUpdate(BaseModel): """ The _meta property is reserved by ACP for additional metadata. Implementations MUST NOT make assumptions about values at these keys. - Optional; omitted and `null` mean no metadata for this state snapshot. + Optional. Omitted and `null` mean no metadata for this state snapshot. """ -class IdleStateUpdate(BaseModel): - stop_reason: Annotated[ - Optional[Literal["end_turn", "max_tokens", "max_turn_requests", "refusal", "cancelled"]], - Field(alias="stopReason"), - ] = None +class IdleStateUpdate1(BaseModel): + usage: Optional[Usage] = None """ - Reason foreground work stopped. Optional; omitted or `null` means not reported. + **UNSTABLE** Token usage for completed foreground work. + + Optional. Omitted or `null` means not reported. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ + The _meta property is reserved by ACP for additional metadata. + Implementations MUST NOT make assumptions about values at these keys. + Optional. Omitted and `null` mean no metadata for this state snapshot. + """ + stop_reason: Annotated[Literal["end_turn"], Field(alias="stopReason")] = "end_turn" + """ + Why foreground work stopped. The value selects one of this type's variants, which may add fields of their own. + + Optional. Omitted or `null` both mean the agent is not reporting a stop reason; a malformed value is treated the same way. + + See protocol docs: [Work state](https://agentclientprotocol.com/protocol/v1/draft/subagents#work-state) + """ + + +class IdleStateUpdate2(BaseModel): usage: Optional[Usage] = None """ **UNSTABLE** Token usage for completed foreground work. - Optional; omitted or `null` means not reported. + Optional. Omitted or `null` means not reported. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ The _meta property is reserved by ACP for additional metadata. Implementations MUST NOT make assumptions about values at these keys. - Optional; omitted and `null` mean no metadata for this state snapshot. + Optional. Omitted and `null` mean no metadata for this state snapshot. """ + stop_reason: Annotated[Literal["max_tokens"], Field(alias="stopReason")] = "max_tokens" + """ + Why foreground work stopped. The value selects one of this type's variants, which may add fields of their own. - @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) + Optional. Omitted or `null` both mean the agent is not reporting a stop reason; a malformed value is treated the same way. + + See protocol docs: [Work state](https://agentclientprotocol.com/protocol/v1/draft/subagents#work-state) + """ + + +class IdleStateUpdate3(BaseModel): + usage: Optional[Usage] = None + """ + **UNSTABLE** Token usage for completed foreground work. + + Optional. Omitted or `null` means not reported. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + The _meta property is reserved by ACP for additional metadata. + Implementations MUST NOT make assumptions about values at these keys. + Optional. Omitted and `null` mean no metadata for this state snapshot. + """ + stop_reason: Annotated[Literal["max_turn_requests"], Field(alias="stopReason")] = "max_turn_requests" + """ + Why foreground work stopped. The value selects one of this type's variants, which may add fields of their own. + + Optional. Omitted or `null` both mean the agent is not reporting a stop reason; a malformed value is treated the same way. + + See protocol docs: [Work state](https://agentclientprotocol.com/protocol/v1/draft/subagents#work-state) + """ + + +class IdleStateUpdate4(BaseModel): + usage: Optional[Usage] = None + """ + **UNSTABLE** Token usage for completed foreground work. + + Optional. Omitted or `null` means not reported. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + The _meta property is reserved by ACP for additional metadata. + Implementations MUST NOT make assumptions about values at these keys. + Optional. Omitted and `null` mean no metadata for this state snapshot. + """ + stop_reason: Annotated[Literal["refusal"], Field(alias="stopReason")] = "refusal" + """ + Why foreground work stopped. The value selects one of this type's variants, which may add fields of their own. + + Optional. Omitted or `null` both mean the agent is not reporting a stop reason; a malformed value is treated the same way. + + See protocol docs: [Work state](https://agentclientprotocol.com/protocol/v1/draft/subagents#work-state) + """ + + +class IdleStateUpdate5(BaseModel): + usage: Optional[Usage] = None + """ + **UNSTABLE** Token usage for completed foreground work. + + Optional. Omitted or `null` means not reported. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + The _meta property is reserved by ACP for additional metadata. + Implementations MUST NOT make assumptions about values at these keys. + Optional. Omitted and `null` mean no metadata for this state snapshot. + """ + stop_reason: Annotated[Literal["cancelled"], Field(alias="stopReason")] = "cancelled" + """ + Why foreground work stopped. The value selects one of this type's variants, which may add fields of their own. + + Optional. Omitted or `null` both mean the agent is not reporting a stop reason; a malformed value is treated the same way. + + See protocol docs: [Work state](https://agentclientprotocol.com/protocol/v1/draft/subagents#work-state) + """ + + +class IdleStateUpdate7(BaseModel): + model_config = ConfigDict( + extra="allow", + ) + usage: Optional[Usage] = None + """ + **UNSTABLE** Token usage for completed foreground work. + + Optional. Omitted or `null` means not reported. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + The _meta property is reserved by ACP for additional metadata. + Implementations MUST NOT make assumptions about values at these keys. + Optional. Omitted and `null` mean no metadata for this state snapshot. + """ + stop_reason: Annotated[str, Field(alias="stopReason")] + """ + Unrecognized stop reason. + """ + + +class IdleStateUpdate8(BaseModel): + usage: Optional[Usage] = None + """ + **UNSTABLE** Token usage for completed foreground work. + + Optional. Omitted or `null` means not reported. + """ + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + The _meta property is reserved by ACP for additional metadata. + Implementations MUST NOT make assumptions about values at these keys. + Optional. Omitted and `null` mean no metadata for this state snapshot. + """ + stop_reason: Annotated[None, Field(alias="stopReason")] = None + """ + Why foreground work stopped. The value selects one of this type's variants, which may add fields of their own. + + Optional. Omitted or `null` both mean the agent is not reporting a stop reason; a malformed value is treated the same way. + + See protocol docs: [Work state](https://agentclientprotocol.com/protocol/v1/draft/subagents#work-state) + """ class RequiresActionStateUpdate(BaseModel): @@ -1657,7 +1972,7 @@ class RequiresActionStateUpdate(BaseModel): """ The _meta property is reserved by ACP for additional metadata. Implementations MUST NOT make assumptions about values at these keys. - Optional; omitted and `null` mean no metadata for this state snapshot. + Optional. Omitted and `null` mean no metadata for this state snapshot. """ @@ -1666,7 +1981,7 @@ class UnknownStateUpdate(BaseModel): """ The _meta property is reserved by ACP for additional metadata. Implementations MUST NOT make assumptions about values at these keys. - Optional; omitted and `null` mean no metadata for this state snapshot. + Optional. Omitted and `null` mean no metadata for this state snapshot. """ @@ -1683,10 +1998,41 @@ class CompleteElicitationNotification(BaseModel): Optional. Omitted and `null` are equivalent and mean no metadata. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ +class AuthStatusUpdateNotification(BaseModel): + state: Union[Literal["authenticated"], Literal["unauthenticated"], Literal["not_required"], Literal["unknown"], str] + """ + Whether the agent can start sessions without the user signing in first. + + Clients use this field to decide whether sign-in is needed. Clients MUST treat + values they do not recognize as `unknown`. + """ + accounts: Optional[List[AuthAccount]] = None + """ + The accounts the agent has configured, for display. + + Optional. Omitted and empty are equivalent and mean no accounts are reported. + Agents that hold credentials for several providers or accounts SHOULD list each + of them and mark the ones in effect with `active`. + """ + 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/v1/draft/extensibility) + """ + + @field_validator("accounts", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + class FileSystemCapabilities(BaseModel): read_text_file: Annotated[Optional[bool], Field(alias="readTextFile")] = False """ @@ -1702,7 +2048,7 @@ class FileSystemCapabilities(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("read_text_file", "write_text_file", mode="wrap") @@ -1722,7 +2068,7 @@ class BooleanConfigOptionCapabilities(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -1730,106 +2076,110 @@ class NoticeCapabilities(BaseModel): pass -class SubagentCapabilities(BaseModel): +class PromptSuggestionsImageCapabilities(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/v1/draft/extensibility) """ -class PlanCapabilities(BaseModel): +class PromptSuggestionsAudioCapabilities(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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class AuthCapabilities(BaseModel): - terminal: Optional[bool] = False - """ - Whether the client supports `terminal` authentication methods. - - The client should set this to `true` only when it can reproduce the - configured agent invocation in an interactive terminal. When `true`, the - agent may include `terminal` entries in its authentication methods. - """ +class PromptSuggestionsEmbeddedContextCapabilities(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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/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 SessionCursorsCapabilities(BaseModel): + pass -class ElicitationFormCapabilities(BaseModel): +class SubagentCapabilities(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/extensibility) """ -class ElicitationUrlCapabilities(BaseModel): +class PlanCapabilities(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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class NesJumpCapabilities(BaseModel): +class AuthCapabilities(BaseModel): + terminal: Optional[bool] = False + """ + Whether the client supports `terminal` authentication methods. + + The client should set this to `true` only when it can reproduce the + configured agent invocation in an interactive terminal. When `true`, 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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/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 NesRenameCapabilities(BaseModel): +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. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class NesSearchAndReplaceCapabilities(BaseModel): +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. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -1845,7 +2195,7 @@ class AuthenticateRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -1856,7 +2206,7 @@ class ListProvidersRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -1887,7 +2237,7 @@ class SetProviderRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -1902,7 +2252,7 @@ class DisableProviderRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -1913,7 +2263,18 @@ class LogoutRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + """ + + +class AuthStatusRequest(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/v1/draft/extensibility) """ @@ -1932,7 +2293,7 @@ class HttpHeader(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -1955,7 +2316,7 @@ class McpServerHttp(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -1978,7 +2339,7 @@ class McpServerSse(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -2000,7 +2361,7 @@ class McpServerAcp(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -2013,32 +2374,13 @@ class McpServerStdio(BaseModel): """ Absolute path to the MCP server executable. """ - args: List[str] - """ - Command-line arguments to pass to the MCP server. - """ - env: List[EnvVariable] - """ - 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/extensibility) - """ - - -class ListSessionsRequest(BaseModel): - cwd: Optional[str] = None + args: List[str] """ - Filter sessions by working directory. Must be an absolute path. + Command-line arguments to pass to the MCP server. """ - cursor: Optional[str] = None + env: List[EnvVariable] """ - Opaque cursor token from a previous response's nextCursor field for cursor-based pagination + Environment variables to set when launching the MCP server. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -2046,14 +2388,14 @@ class ListSessionsRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class DeleteSessionRequest(BaseModel): - session_id: Annotated[str, Field(alias="sessionId")] +class InitialSessionConfigOption1(BaseModel): + config_id: Annotated[str, Field(alias="configId")] """ - The ID of the session to delete. + The ID of the configuration option to set. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -2061,14 +2403,19 @@ class DeleteSessionRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + """ + type: Literal["boolean"] = "boolean" + value: bool + """ + The boolean value. """ -class CloseSessionRequest(BaseModel): - session_id: Annotated[str, Field(alias="sessionId")] +class InitialSessionConfigOption2(BaseModel): + config_id: Annotated[str, Field(alias="configId")] """ - The ID of the session to close. + The ID of the configuration option to set. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -2076,18 +2423,18 @@ class CloseSessionRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + """ + value: str + """ + The value ID. """ -class SetSessionModeRequest(BaseModel): +class DeleteSessionRequest(BaseModel): session_id: Annotated[str, Field(alias="sessionId")] """ - The ID of the session to set the mode for. - """ - mode_id: Annotated[str, Field(alias="modeId")] - """ - The ID of the mode to set. + The ID of the session to delete. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -2095,18 +2442,14 @@ class SetSessionModeRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class SetSessionConfigOptionBooleanRequest(BaseModel): +class ArchiveSessionRequest(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. + The ID of the session to archive. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -2114,23 +2457,14 @@ class SetSessionConfigOptionBooleanRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - value: bool - """ - The boolean value. - """ - type: Literal["boolean"] = "boolean" -class SetSessionConfigOptionSelectRequest(BaseModel): +class UnarchiveSessionRequest(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. + The ID of the session to unarchive. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -2138,22 +2472,14 @@ class SetSessionConfigOptionSelectRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - """ - value: str - """ - The value ID. + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class WorkspaceFolder(BaseModel): - uri: str - """ - The URI of the folder. - """ - name: str +class SessionStatusRequest(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] """ - The display name of the folder. + The ID of the session to check. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -2161,22 +2487,31 @@ class WorkspaceFolder(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class NesRepository(BaseModel): - name: str +class SessionOptionsRequest(BaseModel): + cwd: str """ - The repository name. + The working directory to resolve options for. Must be an absolute path. """ - owner: str + additional_directories: Annotated[Optional[List[str]], Field(alias="additionalDirectories")] = None """ - The repository owner. + Additional workspace roots to resolve options for. Each path must be absolute. + + Optional. Omitted and `null` are equivalent to an empty list. """ - remote_url: Annotated[str, Field(alias="remoteUrl")] + session_id: Annotated[Optional[str], Field(alias="sessionId")] = None """ - The remote URL of the repository. + The session to resolve options for. + + Optional. Omitted and `null` are equivalent and mean a new session. When present, + the Agent returns what `session/load` or `session/resume` with the same `cwd` and + `additionalDirectories` would return, with the same `cwd` rules. A session the + Agent does not know gets `-32002`. + Clients MUST only send this when the Agent supports `session/load` (`loadSession`) + or `session/resume` (`sessionCapabilities.resume`). """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -2184,22 +2519,23 @@ class NesRepository(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class NesRecentFile(BaseModel): - uri: str - """ - The URI of the file. - """ - language_id: Annotated[str, Field(alias="languageId")] +class SetSessionTitleRequest(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] """ - The language identifier. + The ID of the session to retitle. """ - text: str + title: str """ - The full text content of the file. + The new title for the session. + + Required and non-null. Omission and explicit `null` are both invalid. The Agent MAY + normalize the title before storing it, for example by trimming whitespace or + truncating it. The Agent rejects a title that fails its validation, including one + that is empty after normalization, with `-32602`. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -2207,22 +2543,14 @@ class NesRecentFile(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/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 +class CloseSessionRequest(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] """ - The text content of the excerpt. + The ID of the session to close. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -2230,18 +2558,18 @@ class NesExcerpt(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class NesEditHistoryEntry(BaseModel): - uri: str +class SetSessionModeRequest(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] """ - The URI of the edited file. + The ID of the session to set the mode for. """ - diff: str + mode_id: Annotated[str, Field(alias="modeId")] """ - A diff representing the edit. + The ID of the mode to set. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -2249,26 +2577,18 @@ class NesEditHistoryEntry(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class NesUserAction(BaseModel): - action: str - """ - The kind of action (e.g., "insertChar", "cursorMovement"). - """ - uri: str - """ - The URI of the file where the action occurred. - """ - position: Position +class SetSessionConfigOptionBooleanRequest(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] """ - The position where the action occurred. + The ID of the session to set the configuration option for. """ - timestamp_ms: Annotated[int, Field(alias="timestampMs", ge=0)] + config_id: Annotated[str, Field(alias="configId")] """ - Timestamp in milliseconds since epoch. + The ID of the configuration option to set. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -2276,14 +2596,23 @@ class NesUserAction(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + """ + type: Literal["boolean"] = "boolean" + value: bool + """ + The boolean value. """ -class CloseNesRequest(BaseModel): +class SetSessionConfigOptionSelectRequest(BaseModel): session_id: Annotated[str, Field(alias="sessionId")] """ - The ID of the NES session to close. + 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 """ @@ -2291,7 +2620,11 @@ class CloseNesRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + """ + value: str + """ + The value ID. """ @@ -2302,7 +2635,7 @@ class WriteTextFileResponse(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -2317,7 +2650,7 @@ class ReadTextFileResponse(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -2336,7 +2669,7 @@ class SelectedPermissionOutcome(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -2351,7 +2684,7 @@ class CreateTerminalResponse(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -2370,7 +2703,7 @@ class TerminalExitStatus(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("exit_code", "signal", mode="wrap") @@ -2386,7 +2719,7 @@ class ReleaseTerminalResponse(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -2405,7 +2738,7 @@ class WaitForTerminalExitResponse(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("exit_code", "signal", mode="wrap") @@ -2421,7 +2754,7 @@ class KillTerminalResponse(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -2434,7 +2767,7 @@ class DeclineElicitationResponse(BaseModel): Optional. Omitted and `null` are equivalent and mean no metadata. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ action: Literal["decline"] = "decline" @@ -2448,7 +2781,7 @@ class CancelElicitationResponse(BaseModel): Optional. Omitted and `null` are equivalent and mean no metadata. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ action: Literal["cancel"] = "cancel" @@ -2465,7 +2798,7 @@ class OtherElicitationResponse(BaseModel): Optional. Omitted and `null` are equivalent and mean no metadata. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ action: str """ @@ -2480,7 +2813,7 @@ class OtherElicitationResponse(BaseModel): class ElicitationContentValue(RootModel[Union[str, int, float, bool, List[str]]]): root: Union[str, int, float, bool, List[str]] """ - Allowed wire representations for [`ElicitationContentValue`]. + Allowed wire representations for `ElicitationContentValue`. """ @@ -2508,7 +2841,7 @@ class McpError(BaseModel): ) code: StrictInt """ - Inner MCP error code; never an ACP error code. + Inner MCP error code. Never an ACP error code. """ message: str """ @@ -2516,7 +2849,7 @@ class McpError(BaseModel): """ data: Optional[Any] = None """ - Optional error data; explicit null is retained. + Optional error data. Explicit null is retained. """ @@ -2531,49 +2864,28 @@ class CancelNotification(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class DidOpenDocumentNotification(BaseModel): - session_id: Annotated[str, Field(alias="sessionId")] - """ - The session ID for this notification. - """ - uri: str - """ - The URI of the opened document. - """ - language_id: Annotated[str, Field(alias="languageId")] - """ - The language identifier of the document (e.g., "rust", "python"). +class MessageMcpNotification(BaseModel): + server_id: Annotated[str, Field(alias="serverId")] """ - version: int + The declared ACP MCP server handling the associated request. """ - The version number of the document. + request_id: Annotated[str, Field(alias="requestId")] """ - text: str + The identifier of the active inner MCP request. """ - The full text content of the document. + method: str """ - field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + The inner MCP method name. """ - The _meta property is reserved by ACP to allow clients and agents to attach additional - metadata to their interactions. Implementations MUST NOT make assumptions about values at - these keys. - - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + params: Optional[Dict[str, Any]] = None """ + Optional inner MCP params. - -class DidCloseDocumentNotification(BaseModel): - session_id: Annotated[str, Field(alias="sessionId")] - """ - The session ID for this notification. - """ - uri: str - """ - The URI of the closed document. + If omitted or set to `null`, the inner MCP message has no params. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -2581,18 +2893,14 @@ class DidCloseDocumentNotification(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class DidSaveDocumentNotification(BaseModel): - session_id: Annotated[str, Field(alias="sessionId")] - """ - The session ID for this notification. - """ - uri: str +class CancelRequestNotification(BaseModel): + request_id: Annotated[Optional[Union[int, str]], Field(alias="requestId")] """ - The URI of the saved document. + The ID of the request to cancel. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -2600,70 +2908,61 @@ class DidSaveDocumentNotification(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class AcceptNesNotification(BaseModel): - session_id: Annotated[str, Field(alias="sessionId")] +class ProxySuccessorRequest(BaseModel): + method: str """ - The session ID for this notification. + Method name of the wrapped request. """ - id: str + params: Optional[Any] = None """ - The ID of the accepted suggestion. + Params of the wrapped request, forwarded unchanged. + + Optional. Omitted and `null` are equivalent and mean the wrapped request has no params. + When present, it MUST be a JSON object or array, as JSON-RPC requires. + The wrapped request's own `_meta` stays inside these params. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ + Metadata for the `proxy/successor` envelope itself, separate from the wrapped + message's `_meta`. It is hop-local: the conductor does not copy it into the message + it unwraps. + The _meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class MessageMcpNotification(BaseModel): - server_id: Annotated[str, Field(alias="serverId")] - """ - The declared ACP MCP server handling the associated request. - """ - request_id: Annotated[str, Field(alias="requestId")] - """ - The identifier of the active inner MCP request. - """ +class ProxySuccessorNotification(BaseModel): method: str """ - The inner MCP method name. + Method name of the wrapped notification. """ - params: Optional[Dict[str, Any]] = None + params: Optional[Any] = None """ - Optional inner MCP params. + Params of the wrapped notification, forwarded unchanged. - If omitted or set to `null`, the inner MCP message has no params. + Optional. Omitted and `null` are equivalent and mean the wrapped notification has no params. + When present, it MUST be a JSON object or array, as JSON-RPC requires. + The wrapped notification's own `_meta` stays inside these 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/extensibility) - """ - + Metadata for the `proxy/successor` envelope itself, separate from the wrapped + message's `_meta`. It is hop-local: the conductor does not copy it into the message + it unwraps. -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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -2686,7 +2985,7 @@ class WriteTextFileRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -2698,6 +2997,10 @@ class TerminalToolCallContent(Terminal): type: Literal["terminal"] = "terminal" +class ToolCallContentSession(SessionReference): + type: Literal["session"] = "session" + + class Annotations(BaseModel): audience: Optional[List[Literal["assistant", "user"]]] = None """ @@ -2717,7 +3020,7 @@ class Annotations(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("last_modified", "priority", mode="wrap") @@ -2746,7 +3049,7 @@ class TextContent(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("annotations", mode="wrap") @@ -2778,7 +3081,7 @@ class ImageContent(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("annotations", "uri", mode="wrap") @@ -2806,7 +3109,7 @@ class AudioContent(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("annotations", mode="wrap") @@ -2850,7 +3153,7 @@ class ResourceLink(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("annotations", "description", "mime_type", "size", "title", mode="wrap") @@ -2874,7 +3177,7 @@ class EmbeddedResource(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("annotations", mode="wrap") @@ -2902,7 +3205,7 @@ class PermissionOption(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -2944,19 +3247,9 @@ class CreateTerminalRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - @field_validator("cwd", "output_byte_limit", 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 CreateUrlSessionElicitationRequestBase(ElicitationSessionScope): elicitation_id: Annotated[str, Field(alias="elicitationId")] @@ -2993,7 +3286,7 @@ class CreateUrlSessionElicitationRequest(CreateUrlSessionElicitationRequestBase, Optional. Omitted and `null` are equivalent and mean no metadata. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ mode: Literal["url"] = "url" @@ -3011,7 +3304,7 @@ class CreateUrlRequestElicitationRequest(CreateUrlRequestElicitationRequestBase, Optional. Omitted and `null` are equivalent and mean no metadata. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ mode: Literal["url"] = "url" @@ -3032,7 +3325,7 @@ class CreateOtherSessionElicitationRequest(ElicitationSessionScope): Optional. Omitted and `null` are equivalent and mean no metadata. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ mode: str """ @@ -3060,7 +3353,7 @@ class CreateOtherRequestElicitationRequest(ElicitationRequestScope): Optional. Omitted and `null` are equivalent and mean no metadata. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ mode: str """ @@ -3135,7 +3428,7 @@ class MultiSelectPropertySchema(BaseModel): Optional. Omitted and `null` are equivalent and mean no metadata. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("description", "title", mode="wrap") @@ -3149,88 +3442,24 @@ def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHand return skip_invalid_items(v, handler, info) -class MessageMcpRequest(BaseModel): - server_id: Annotated[str, Field(alias="serverId")] - """ - The declared ACP MCP server receiving this request. - """ - request_id: Annotated[str, Field(alias="requestId")] - """ - The caller-generated identifier for the inner MCP request. - """ - 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/extensibility) - """ - - -class SessionCapabilities(BaseModel): - list: Optional[SessionListCapabilities] = None - """ - Whether the agent supports `session/list`. - - Optional. Omitted or `null` both mean the agent does not advertise support. - Supplying `{}` means the agent supports listing 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 that also support `session/list` 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. +class MessageMcpRequest(BaseModel): + server_id: Annotated[str, Field(alias="serverId")] """ - resume: Optional[SessionResumeCapabilities] = None + The declared ACP MCP server receiving this request. """ - Whether the agent supports `session/resume`. - - Optional. Omitted or `null` both mean the agent does not advertise support. - Supplying `{}` means the agent supports resuming sessions. + request_id: Annotated[str, Field(alias="requestId")] """ - close: Optional[SessionCloseCapabilities] = None + The caller-generated identifier for the inner MCP request. """ - Whether the agent supports `session/close`. + method: str + """ + The inner MCP method name. + """ + params: Optional[Dict[str, Any]] = None + """ + Optional inner MCP params. - Optional. Omitted or `null` both mean the agent does not advertise support. - Supplying `{}` means the agent supports closing sessions. + If omitted or set to `null`, the inner MCP message has no params. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -3238,22 +3467,18 @@ class SessionCapabilities(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - @field_validator("additional_directories", "close", "delete", "fork", "list", "resume", 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 AgentAuthCapabilities(BaseModel): - logout: Optional[LogoutCapabilities] = None +class SessionSystemPromptModeCapabilities(BaseModel): + override: Optional[SessionSystemPromptOverrideCapabilities] = None """ - Whether the agent supports the logout method. + Whether the agent supports `override` mode. Optional. Omitted or `null` both mean the agent does not advertise support. - Supplying `{}` means the agent supports the logout method. + Supplying `{}` means the agent supports replacing its built-in default + instructions with the client-provided system prompt. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -3261,54 +3486,33 @@ class AgentAuthCapabilities(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - @field_validator("logout", mode="wrap") + @field_validator("override", 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 +class AgentAuthCapabilities(BaseModel): + status: Optional[AuthStatusCapabilities] = 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. + **UNSTABLE** - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - """ + This capability is not part of the spec yet, and may be removed or changed at any point. + Whether the agent supports the `auth/status` method. -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. + Optional. Omitted or `null` both mean the agent does not advertise support. + Supplying `{}` means the agent supports the `auth/status` method. """ - diagnostics: Optional[NesDiagnosticsCapabilities] = None + logout: Optional[LogoutCapabilities] = None """ - Whether the agent wants diagnostics context. + Whether the agent supports the logout method. + + Optional. Omitted or `null` both mean the agent does not advertise support. + Supplying `{}` means the agent supports the logout method. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -3316,12 +3520,10 @@ class NesContextCapabilities(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - @field_validator( - "diagnostics", "edit_history", "open_files", "recent_files", "related_snippets", "user_actions", mode="wrap" - ) + @field_validator("logout", "status", 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) @@ -3358,7 +3560,7 @@ class ProviderInfo(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("supported", mode="wrap") @@ -3367,6 +3569,37 @@ def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHand return skip_invalid_items(v, handler, info) +class AuthStatusResponse(BaseModel): + state: Union[Literal["authenticated"], Literal["unauthenticated"], Literal["not_required"], Literal["unknown"], str] + """ + Whether the agent can start sessions without the user signing in first. + + Clients use this field to decide whether sign-in is needed. Clients MUST treat + values they do not recognize as `unknown`. + """ + accounts: Optional[List[AuthAccount]] = None + """ + The accounts the agent has configured, for display. + + Optional. Omitted and empty are equivalent and mean no accounts are reported. + Agents that hold credentials for several providers or accounts SHOULD list each + of them and mark the ones in effect with `active`. + """ + 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/v1/draft/extensibility) + """ + + @field_validator("accounts", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + + class SessionModeState(BaseModel): current_mode_id: Annotated[str, Field(alias="currentModeId")] """ @@ -3382,7 +3615,7 @@ class SessionModeState(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("available_modes", mode="wrap") @@ -3405,7 +3638,9 @@ class SessionConfigOptionBoolean(SessionConfigBoolean): Optional description for the Client to display to the user. """ category: Optional[ - Union[Literal["mode"], Literal["model"], Literal["model_config"], Literal["thought_level"], str] + Union[ + Literal["mode"], Literal["model"], Literal["model_config"], Literal["speed"], Literal["thought_level"], str + ] ] = None """ Optional semantic category for this option (UX only). @@ -3416,7 +3651,7 @@ class SessionConfigOptionBoolean(SessionConfigBoolean): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ type: Literal["boolean"] = "boolean" @@ -3440,7 +3675,7 @@ class SessionConfigSelectGroup(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("options", mode="wrap") @@ -3465,7 +3700,7 @@ class ListSessionsResponse(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("next_cursor", mode="wrap") @@ -3479,6 +3714,23 @@ def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHand return skip_invalid_items(v, handler, info) +class SessionStatusResponse(BaseModel): + status: Union[Literal["open"], Literal["saved"], str] + """ + Whether the Agent has the session in memory. + + Required. Clients MUST treat a value they do not recognize as `saved`. + """ + 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/v1/draft/extensibility) + """ + + class PromptResponse(BaseModel): stop_reason: Annotated[ Literal["end_turn", "max_tokens", "max_turn_requests", "refusal", "cancelled"], Field(alias="stopReason") @@ -3500,7 +3752,7 @@ class PromptResponse(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("usage", mode="wrap") @@ -3509,37 +3761,6 @@ def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHa return use_default_on_error(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 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/extensibility) - """ - - class Error(BaseModel): code: Union[ Literal[-32700], @@ -3623,7 +3844,7 @@ class PlanEntry(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -3641,7 +3862,7 @@ class Plan(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("entries", mode="wrap") @@ -3650,177 +3871,21 @@ def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHand return skip_invalid_items(v, handler, info) -class PlanUpdateFile(PlanFile): - type: Literal["file"] = "file" - - class PlanUpdateMarkdown(PlanMarkdown): type: Literal["markdown"] = "markdown" -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/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 AvailableCommandInput(RootModel[UnstructuredCommandInput]): - root: UnstructuredCommandInput - """ - The input specification for a command. - """ - - -class SubagentSessionCapabilities(BaseModel): - cancel: Optional[SessionCancelCapabilities] = None - """ - Permits the client to cancel this child's current work without ending - the session. Omitted or `null` means unsupported; an object (including - `{}`) means supported. - """ - 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. - """ - - @field_validator("cancel", 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 StateUpdate1(RunningStateUpdate): - state: Literal["running"] = "running" - - -class StateUpdate2(IdleStateUpdate): - state: Literal["idle"] = "idle" - - -class StateUpdate3(RequiresActionStateUpdate): - state: Literal["requires_action"] = "requires_action" - - -class StateUpdate4(UnknownStateUpdate): - state: Literal["unknown"] = "unknown" - - -class SubagentUpdate(BaseModel): - session_id: Annotated[str, Field(alias="sessionId")] - """ - The opaque session ID identifying the child in all ACP messages. - """ - title: Optional[str] = None - """ - The parent's human-readable display title for this child. It need not be unique. - - Omitted means unchanged; `null` clears it. If unset, the Client chooses - a fallback presentation. - """ - description: Optional[str] = None - """ - The parent's human-readable description of the child's role or purpose. - - Omitted means unchanged; `null` clears it. If unset, the Client chooses - a fallback presentation. This is current display metadata, not the - history of instructions sent to the child. - """ - capabilities: Optional[SubagentSessionCapabilities] = None - """ - Client-initiated session mutations permitted for this subagent session. - - Omitted means unchanged; `null` clears the capability set and disables - child mutations. If never supplied, no session mutations are permitted. - Read-only operations retain their normal protocol semantics and capability - requirements. A concrete object replaces the whole capability set. - """ - state: Optional[Union[StateUpdate1, StateUpdate2, StateUpdate3, StateUpdate4, StateUpdate5]] = None - """ - Current state snapshot for the child session. - - Omitted means unchanged; `null` clears the current activity without - asserting idle or sending an `unknown` snapshot. A concrete state - replaces the previous state object wholesale. If never supplied, the - current activity is unset/unconfirmed. - """ - 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/extensibility) - Omitted means unchanged; `null` removes the metadata. - """ - - @field_validator("capabilities", "description", "state", "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 SessionConfigOptionsCapabilities(BaseModel): - boolean: Optional[BooleanConfigOptionCapabilities] = None - """ - Whether the client supports boolean session configuration options. - - Optional. Omitted or `null` both mean the client does not advertise support. - Supplying `{}` means agents may include `type: "boolean"` entries in - `configOptions`, and the client may send `session/set_config_option` - requests with `type: "boolean"` and a boolean `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/extensibility) - """ - - @field_validator("boolean", 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. +class PlanItems(BaseModel): + plan_id: Annotated[str, Field(alias="planId")] """ - url: Optional[ElicitationUrlCapabilities] = None + The plan ID to update. """ - Whether the client supports URL-based elicitation. + entries: List[PlanEntry] + """ + The list of tasks to be accomplished. - Optional. Omitted or `null` both mean the client does not advertise support. - Supplying `{}` means the client supports URL-based elicitation. + 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 """ @@ -3828,185 +3893,212 @@ class ElicitationCapabilities(BaseModel): 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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - @field_validator("form", "url", mode="wrap") + @field_validator("entries", 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) + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) -class ClientNesCapabilities(BaseModel): - jump: Optional[NesJumpCapabilities] = None - """ - Whether the client supports the `jump` suggestion kind. - """ - rename: Optional[NesRenameCapabilities] = None +class AvailableCommandInput(RootModel[UnstructuredCommandInput]): + root: UnstructuredCommandInput """ - Whether the client supports the `rename` suggestion kind. + The input specification for a command. """ - search_and_replace: Annotated[Optional[NesSearchAndReplaceCapabilities], Field(alias="searchAndReplace")] = None + + +class CursorCapabilities(BaseModel): + fork: Optional[CursorForkCapabilities] = None """ - Whether the client supports the `searchAndReplace` suggestion kind. + Permits the Client to fork the session at this cursor with `session/fork`. + + Omitted and `null` are equivalent and mean unsupported. An object (including `{}`) + means supported. """ 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. + metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. + Implementations MUST NOT assign meaning to keys they do not recognize. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - @field_validator("jump", "rename", "search_and_replace", mode="wrap") + @field_validator("fork", 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 CursorAnchor1(CursorMessageAnchor): + type: Literal["user_message"] = "user_message" -class SseMcpServer(McpServerSse): - type: Literal["sse"] = "sse" +class CursorAnchor2(CursorMessageAnchor): + type: Literal["agent_message"] = "agent_message" -class AcpMcpServer(McpServerAcp): - type: Literal["acp"] = "acp" +class CursorAnchor3(CursorMessageAnchor): + type: Literal["agent_thought"] = "agent_thought" -class LoadSessionRequest(BaseModel): - mcp_servers: Annotated[ - List[Union[HttpMcpServer, SseMcpServer, AcpMcpServer, McpServerStdio]], Field(alias="mcpServers") - ] - """ - List of MCP servers to connect to for this session. - """ - cwd: str +class CursorAnchor4(CursorMessageAnchor): + type: Literal["session_message"] = "session_message" + + +class CursorAnchor5(CursorToolCallAnchor): + type: Literal["tool_call"] = "tool_call" + + +class CursorAnchor6(CursorCompactionAnchor): + type: Literal["compaction"] = "compaction" + + +class CursorUpdate(BaseModel): + cursor_id: Annotated[str, Field(alias="cursorId")] """ - The working directory for this session. Must be an absolute path. + The Agent-owned ID of this cursor, unique within the session. """ - additional_directories: Annotated[Optional[List[str]], Field(alias="additionalDirectories")] = None + capabilities: Optional[CursorCapabilities] = None """ - Additional workspace roots to activate for this session. Each path must be absolute. + The methods that currently accept this cursor. - When omitted or empty, no additional roots are activated. When non-empty, - this is the complete resulting additional-root list for the loaded - session. It may differ from any previously used or reported list as long as - the request `cwd` matches the session's `cwd`. + Omission leaves the capabilities unchanged, `null` clears them, and an object replaces + the whole previous value. A new cursor starts with none. """ - session_id: Annotated[str, Field(alias="sessionId")] + anchor: Optional[ + Union[CursorAnchor1, CursorAnchor2, CursorAnchor3, CursorAnchor4, CursorAnchor5, CursorAnchor6, CursorAnchor7] + ] = None """ - The ID of the session to load. + Where the cursor is, relative to an entity the Client holds. + + Required on the first update for a cursor. The Agent MUST NOT change it afterwards. + A later update can omit it or repeat the same anchor. Omitted and `null` are + equivalent and leave the stored anchor unchanged. """ 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/extensibility) + Extensible metadata patch for this cursor. """ - @field_validator("additional_directories", "mcp_servers", mode="wrap") + @field_validator("capabilities", mode="wrap") @classmethod - def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: - return skip_invalid_items(v, handler, info) - + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) -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, SseMcpServer, AcpMcpServer, McpServerStdio]]], Field(alias="mcpServers") - ] = None +class SubagentSessionCapabilities(BaseModel): + cancel: Optional[SessionCancelCapabilities] = None """ - List of MCP servers to connect to for this session. + Permits the client to cancel this child's current work without ending + the session. Omitted or `null` means unsupported. An object (including + `{}`) means supported. """ 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/extensibility) """ - @field_validator("additional_directories", "mcp_servers", mode="wrap") + @field_validator("cancel", mode="wrap") @classmethod - def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: - return skip_invalid_items(v, handler, info) + def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return use_default_on_error(v, handler, info) -class ResumeSessionRequest(BaseModel): - session_id: Annotated[str, Field(alias="sessionId")] - """ - The ID of the session to resume. - """ - cwd: str +class StateUpdate1(RunningStateUpdate): + state: Literal["running"] = "running" + + +class StateUpdate3(RequiresActionStateUpdate): + state: Literal["requires_action"] = "requires_action" + + +class StateUpdate4(UnknownStateUpdate): + state: Literal["unknown"] = "unknown" + + +class ErrorStopReason(BaseModel): + error: Optional[Error] = None """ - The working directory for this session. Must be an absolute path. + The failure, as a JSON-RPC error object. + + Optional. Omitted or `null` both mean the agent is not reporting failure details. + Agents SHOULD include it. """ - additional_directories: Annotated[Optional[List[str]], Field(alias="additionalDirectories")] = None + + @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) + + +class IdleStateUpdate6(ErrorStopReason): + usage: Optional[Usage] = None """ - Additional workspace roots to activate for this session. Each path must be absolute. + **UNSTABLE** Token usage for completed foreground work. - 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`. + Optional. Omitted or `null` means not reported. """ - mcp_servers: Annotated[ - Optional[List[Union[HttpMcpServer, SseMcpServer, AcpMcpServer, McpServerStdio]]], Field(alias="mcpServers") - ] = None + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ - List of MCP servers to connect to for this session. + The _meta property is reserved by ACP for additional metadata. + Implementations MUST NOT make assumptions about values at these keys. + Optional. Omitted and `null` mean no metadata for this state snapshot. """ - field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + stop_reason: Annotated[Literal["error"], Field(alias="stopReason")] = "error" """ - The _meta property is reserved by ACP to allow clients and agents to attach additional - metadata to their interactions. Implementations MUST NOT make assumptions about values at - these keys. + Why foreground work stopped. The value selects one of this type's variants, which may add fields of their own. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - """ + Optional. Omitted or `null` both mean the agent is not reporting a stop reason; a malformed value is treated the same way. - @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) + See protocol docs: [Work state](https://agentclientprotocol.com/protocol/v1/draft/subagents#work-state) + """ -class StartNesRequest(BaseModel): - workspace_uri: Annotated[Optional[str], Field(alias="workspaceUri")] = None - """ - The root URI of the workspace. - """ - workspace_folders: Annotated[Optional[List[WorkspaceFolder]], Field(alias="workspaceFolders")] = None +class IdleStateUpdate( + RootModel[ + Union[ + IdleStateUpdate1, + IdleStateUpdate2, + IdleStateUpdate3, + IdleStateUpdate4, + IdleStateUpdate5, + IdleStateUpdate6, + IdleStateUpdate7, + IdleStateUpdate8, + ] + ] +): + root: Union[ + IdleStateUpdate1, + IdleStateUpdate2, + IdleStateUpdate3, + IdleStateUpdate4, + IdleStateUpdate5, + IdleStateUpdate6, + IdleStateUpdate7, + IdleStateUpdate8, + ] """ - The workspace folders. + The child is ready to process another prompt. + + An omitted, `null`, or malformed `stopReason` means not reported. """ - repository: Optional[NesRepository] = None + + +class SessionConfigOptionsCapabilities(BaseModel): + boolean: Optional[BooleanConfigOptionCapabilities] = None """ - Repository metadata, if the workspace is a git repository. + Whether the client supports boolean session configuration options. + + Optional. Omitted or `null` both mean the client does not advertise support. + Supplying `{}` means agents may include `type: "boolean"` entries in + `configOptions`, and the client may send `session/set_config_option` + requests with `type: "boolean"` and a boolean `value`. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -4014,23 +4106,39 @@ class StartNesRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - @field_validator("repository", "workspace_uri", mode="wrap") + @field_validator("boolean", 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: str +class PromptSuggestionsCapabilities(BaseModel): + image: Optional[PromptSuggestionsImageCapabilities] = None + """ + Whether prompt suggestions may include `image` content blocks. + + Optional. Omitted or `null` both mean the client does not advertise support. + Supplying `{}` means the client can offer suggestions that include images. + """ + audio: Optional[PromptSuggestionsAudioCapabilities] = None """ - The URI of the file containing the snippets. + Whether prompt suggestions may include `audio` content blocks. + + Optional. Omitted or `null` both mean the client does not advertise support. + Supplying `{}` means the client can offer suggestions that include audio. """ - excerpts: List[NesExcerpt] + embedded_context: Annotated[ + Optional[PromptSuggestionsEmbeddedContextCapabilities], Field(alias="embeddedContext") + ] = None """ - The code excerpts. + Whether prompt suggestions may include `resource` content blocks. + + Optional. Omitted or `null` both mean the client does not advertise support. + Supplying `{}` means the client can offer suggestions that include + embedded resources. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -4038,26 +4146,29 @@ class NesRelatedSnippet(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/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 NesOpenFile(BaseModel): - uri: str - """ - The URI of the file. - """ - language_id: Annotated[str, Field(alias="languageId")] - """ - The language identifier. - """ - visible_range: Annotated[Optional[Range], Field(alias="visibleRange")] = None + +class ElicitationCapabilities(BaseModel): + form: Optional[ElicitationFormCapabilities] = None """ - The visible range in the editor, if any. + 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. """ - last_focused_ms: Annotated[Optional[int], Field(alias="lastFocusedMs", ge=0)] = None + url: Optional[ElicitationUrlCapabilities] = None """ - Timestamp in milliseconds since epoch of when the file was last focused. + 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 """ @@ -4065,31 +4176,49 @@ class NesOpenFile(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + Optional. Omitted and `null` are equivalent and mean no metadata. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - @field_validator("last_focused_ms", "visible_range", mode="wrap") + @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 NesDiagnostic(BaseModel): - uri: str - """ - The URI of the file containing the diagnostic. - """ - range: Range +class HttpMcpServer(McpServerHttp): + type: Literal["http"] = "http" + + +class SseMcpServer(McpServerSse): + type: Literal["sse"] = "sse" + + +class AcpMcpServer(McpServerAcp): + type: Literal["acp"] = "acp" + + +class ListSessionsRequest(BaseModel): + cwd: Optional[str] = None """ - The range of the diagnostic. + Filter sessions by working directory. Must be an absolute path. """ - severity: Literal["error", "warning", "information", "hint"] + cursor: Optional[str] = None """ - The severity of the diagnostic. + Opaque cursor token from a previous response's nextCursor field for cursor-based pagination """ - message: str + archived: Optional[Union[Literal["exclude"], Literal["include"], Literal["only"], str]] = None """ - The diagnostic message. + **UNSTABLE** + + This capability is not part of the spec yet, and may be removed or changed at any point. + + Filter sessions by archive state. + + Optional. Omitted and `null` are equivalent and mean `exclude`. Only send this when + the Agent advertises the `sessionCapabilities.archive` capability. The filter combines with `cwd` and + applies before pagination. Clients keep the same value when following `nextCursor`. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -4097,7 +4226,7 @@ class NesDiagnostic(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -4135,7 +4264,7 @@ class TerminalOutputResponse(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("exit_status", mode="wrap") @@ -4153,7 +4282,7 @@ class AcceptElicitationResponse(ElicitationAcceptAction): Optional. Omitted and `null` are equivalent and mean no metadata. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ action: Literal["accept"] = "accept" @@ -4165,87 +4294,42 @@ class McpErrorResponse(BaseModel): """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ - Optional ACP carrier metadata. - """ - - -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/extensibility) - """ - - -class DidFocusDocumentNotification(BaseModel): - session_id: Annotated[str, Field(alias="sessionId")] - """ - The session ID for this notification. - """ - uri: str - """ - The URI of the focused document. - """ - version: int - """ - The version number of the document. - """ - position: Position - """ - The current cursor position. + Optional ACP carrier metadata. """ - visible_range: Annotated[Range, Field(alias="visibleRange")] + + +class ClientNotification(BaseModel): + method: str """ - The portion of the file currently visible in the editor viewport. + The notification method name. """ - field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + params: Optional[Union[CancelNotification, MessageMcpNotification, Any]] = None """ - The _meta property is reserved by ACP to allow clients and agents to attach additional - metadata to their interactions. Implementations MUST NOT make assumptions about values at - these keys. - - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + Method-specific notification parameters. """ -class RejectNesNotification(BaseModel): - session_id: Annotated[str, Field(alias="sessionId")] +class ProxyResponse2(BaseModel): + id: Optional[Union[int, str]] """ - The session ID for this notification. + The id of the request this response answers. """ - id: str + error: Error """ - The ID of the rejected suggestion. + Method-specific error data. """ - reason: Optional[Literal["rejected", "ignored", "replaced", "cancelled"]] = None + + +class ProxyNotification(BaseModel): + method: str """ - The reason for rejection. + The notification method name. """ - field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + params: Optional[ProxySuccessorNotification] = None """ - The _meta property is reserved by ACP to allow clients and agents to attach additional - metadata to their interactions. Implementations MUST NOT make assumptions about values at - these keys. - - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + Method-specific notification parameters. """ - @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 TextContentBlock(TextContent): type: Literal["text"] = "text" @@ -4283,7 +4367,7 @@ class Content(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -4302,26 +4386,12 @@ class AgentErrorMessage(BaseModel): """ -class NesDocumentEventCapabilities(BaseModel): - did_open: Annotated[Optional[NesDocumentDidOpenCapabilities], Field(alias="didOpen")] = None +class SessionSystemPromptCapabilities(BaseModel): + mode: Optional[SessionSystemPromptModeCapabilities] = 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. + Delivery modes the agent supports in addition to `append`. + + Optional. Omitted or `null` both mean the agent supports only `append`. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -4329,10 +4399,10 @@ class NesDocumentEventCapabilities(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - @field_validator("did_change", "did_close", "did_focus", "did_open", "did_save", mode="wrap") + @field_validator("mode", 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) @@ -4349,7 +4419,7 @@ class ListProvidersResponse(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -4364,14 +4434,30 @@ class SessionConfigSelect(BaseModel): """ -class NesTextEdit(BaseModel): - range: Range +class AgentPlanUpdate(Plan): + session_update: Annotated[Literal["plan"], Field(alias="sessionUpdate")] = "plan" + + +class SessionUpdateCursorUpdate(CursorUpdate): + session_update: Annotated[Literal["cursor_update"], Field(alias="sessionUpdate")] = "cursor_update" + + +class ContentChunk(BaseModel): + content: Annotated[ + Union[ + TextContentBlock, ImageContentBlock, AudioContentBlock, ResourceContentBlock, EmbeddedResourceContentBlock + ], + Field(discriminator="type"), + ] """ - The range to replace. + A single item of content """ - new_text: Annotated[str, Field(alias="newText")] + message_id: Annotated[Optional[str], Field(alias="messageId")] = None """ - The replacement text. + 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. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -4379,26 +4465,46 @@ class NesTextEdit(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ + @field_validator("message_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 NesEditSuggestion(BaseModel): - id: str +class PlanUpdateItems(PlanItems): + type: Literal["items"] = "items" + + +class PlanUpdate(BaseModel): + plan: Annotated[Union[PlanUpdateItems, PlanUpdateMarkdown], Field(discriminator="type")] """ - Unique identifier for accept/reject tracking. + The updated plan content. """ - uri: str + 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/v1/draft/extensibility) """ - The URI of the file to edit. + + +class AvailableCommand(BaseModel): + name: str """ - edits: List[NesTextEdit] + Command name (e.g., `create_plan`, `research_codebase`). + """ + description: str """ - The text edits to apply. + Human-readable description of what the command does. """ - cursor_position: Annotated[Optional[Position], Field(alias="cursorPosition")] = None + input: Optional[AvailableCommandInput] = None """ - Optional suggested cursor position after applying edits. + Input for the command if required """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -4406,24 +4512,81 @@ class NesEditSuggestion(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - @field_validator("cursor_position", mode="wrap") + @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 AgentPlanUpdate(Plan): - session_update: Annotated[Literal["plan"], Field(alias="sessionUpdate")] = "plan" +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/v1/draft/extensibility) + """ -class SessionUpdateSubagentUpdate(SubagentUpdate): - session_update: Annotated[Literal["subagent_update"], Field(alias="sessionUpdate")] = "subagent_update" +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[ + Annotated[ + Union[ + TextContentBlock, + ImageContentBlock, + AudioContentBlock, + ResourceContentBlock, + EmbeddedResourceContentBlock, + ], + Field(discriminator="type"), + ] + ] + ] = None + """ + Complete replacement user-displayable summary content for the compaction. + """ + error: Optional[str] = None + """ + Human-readable error details for the compaction. + """ + 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) -class ContentChunk(BaseModel): + @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: Annotated[ Union[ TextContentBlock, ImageContentBlock, AudioContentBlock, ResourceContentBlock, EmbeddedResourceContentBlock @@ -4431,14 +4594,42 @@ class ContentChunk(BaseModel): Field(discriminator="type"), ] """ - A single item of content + One content block to append. """ - message_id: Annotated[Optional[str], Field(alias="messageId")] = None + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + """ + Metadata scoped to this chunk. Omission and `null` both mean absent. """ - 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. + +class PromptSuggestion(BaseModel): + prompt: Annotated[ + List[ + Annotated[ + Union[ + TextContentBlock, + ImageContentBlock, + AudioContentBlock, + ResourceContentBlock, + EmbeddedResourceContentBlock, + ], + Field(discriminator="type"), + ] + ], + Field(min_length=1), + ] + """ + The content of the suggested prompt. + + Required and non-null. Must contain at least one content block. This is + the same type as the `prompt` field of `session/prompt`, and the Client + can send it in that field unchanged. + + Agents MUST only use `text` and `resource_link` content blocks, and + other content block types that both the Agent's prompt capabilities + and the Client's `session.promptSuggestions` capability advertise. + Agents MUST NOT send a prompt whose only content is empty or + whitespace-only text. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -4446,23 +4637,18 @@ class ContentChunk(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - @field_validator("message_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 PlanUpdateItems(PlanItems): - type: Literal["items"] = "items" - -class PlanUpdate(BaseModel): - plan: Annotated[Union[PlanUpdateItems, PlanUpdateFile, PlanUpdateMarkdown], Field(discriminator="type")] +class PromptSuggestionsUpdate(BaseModel): + suggestions: List[PromptSuggestion] """ - The updated plan content. + The suggestions the Client can offer, ordered most likely first. + + Required and non-null. An empty list withdraws the suggestions the + Client is offering. A Client skips an entry it cannot parse and keeps + the rest. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -4470,22 +4656,113 @@ class PlanUpdate(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ + @field_validator("suggestions", mode="wrap") + @classmethod + def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: + return skip_invalid_items(v, handler, info) + -class AvailableCommand(BaseModel): - name: str +class StateUpdate26(ErrorStopReason): + usage: Optional[Usage] = None """ - Command name (e.g., `create_plan`, `research_codebase`). + **UNSTABLE** Token usage for completed foreground work. + + Optional. Omitted or `null` means not reported. """ - description: str + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ - Human-readable description of what the command does. + The _meta property is reserved by ACP for additional metadata. + Implementations MUST NOT make assumptions about values at these keys. + Optional. Omitted and `null` mean no metadata for this state snapshot. + """ + stop_reason: Annotated[Literal["error"], Field(alias="stopReason")] = "error" + """ + Why foreground work stopped. The value selects one of this type's variants, which may add fields of their own. + + Optional. Omitted or `null` both mean the agent is not reporting a stop reason; a malformed value is treated the same way. + + See protocol docs: [Work state](https://agentclientprotocol.com/protocol/v1/draft/subagents#work-state) + """ + + +class StateUpdate215(StateUpdate26, StateUpdate29): + state: Literal["idle"] = "idle" + + +class SubagentUpdate(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The opaque session ID identifying the child in all ACP messages. + """ + title: Optional[str] = None + """ + The parent's human-readable display title for this child. It need not be unique. + + Omitted means unchanged. `null` clears it. If unset, the Client chooses + a fallback presentation. + """ + description: Optional[str] = None + """ + The parent's human-readable description of the child's role or purpose. + + Omitted means unchanged. `null` clears it. If unset, the Client chooses + a fallback presentation. This is current display metadata, not the + history of instructions sent to the child. + """ + capabilities: Optional[SubagentSessionCapabilities] = None + """ + Client-initiated session mutations permitted for this subagent session. + + Omitted means unchanged. `null` clears the capability set and disables + child mutations. If never supplied, no session mutations are permitted. + Read-only operations retain their normal protocol semantics and capability + requirements. A concrete object replaces the whole capability set. + """ + state: Optional[ + Union[ + StateUpdate1, + StateUpdate3, + StateUpdate4, + StateUpdate5, + StateUpdate210, + StateUpdate211, + StateUpdate212, + StateUpdate213, + StateUpdate214, + StateUpdate215, + StateUpdate216, + StateUpdate217, + ] + ] = None + """ + Current state snapshot for the child session. + + Omitted means unchanged. `null` clears the current activity without + asserting idle or sending an `unknown` snapshot. A concrete state + replaces the previous state object wholesale. If never supplied, the + current activity is unset/unconfirmed. + """ + cwd: Optional[str] = None + """ + The child's working directory. Must be an absolute path. + + Optional and nullable. Omitted means unchanged. `null` clears the + reported value. While unset, the child inherits its immediate parent's + effective working directory. Clients use this value for the child's + root set and as the default terminal working directory. """ - input: Optional[AvailableCommandInput] = None + additional_directories: Annotated[Optional[List[str]], Field(alias="additionalDirectories")] = None """ - Input for the command if required + Additional workspace roots for the child. Each path must be absolute. + + Optional and nullable. Omitted means unchanged. `null` clears the + reported value. While unset, the child inherits its immediate parent's + effective additional directories, independently of `cwd`. A concrete + array replaces the whole list. `[]` reports no additional directories. + Clients use these values for the child's root set. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -4493,40 +4770,50 @@ class AvailableCommand(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + Omitted means unchanged. `null` removes the metadata. """ - @field_validator("input", mode="wrap") + @field_validator("capabilities", "description", "state", "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 AvailableCommandsUpdateBase(BaseModel): - available_commands: Annotated[List[AvailableCommand], Field(alias="availableCommands")] +class SessionMessage(BaseModel): + message_id: Annotated[str, Field(alias="messageId")] """ - Commands the agent can execute + Identifier of this message within the enclosing session's transcript. """ - field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + sender_session_id: Annotated[Optional[str], Field(alias="senderSessionId")] = 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. + The sending session. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + Omitted leaves the stored value unchanged. `null` clears it. A value replaces it. """ + recipient_session_id: Annotated[Optional[str], Field(alias="recipientSessionId")] = None + """ + The receiving session. - -class CompactionUpdate(BaseModel): - compaction_id: Annotated[str, Field(alias="compactionId")] + Omitted leaves the stored value unchanged. `null` clears it. A value replaces it. """ - The Agent-owned ID of this compaction, unique within the session. + sender_message_id: Annotated[Optional[str], Field(alias="senderMessageId")] = None """ - status: Union[Literal["in_progress"], Literal["completed"], Literal["failed"], Literal["cancelled"], str] + On an incoming view, the `messageId` of the same message's outgoing view in the + sender's transcript. + + Omitted leaves the stored value unchanged. `null` clears it. A value replaces it. It can arrive + after the message starts streaming. """ - Current lifecycle status. + recipient_message_id: Annotated[Optional[str], Field(alias="recipientMessageId")] = None """ - summary: Optional[ + On an outgoing view, the `messageId` of the same message's incoming view in the + recipient's transcript. + + Omitted leaves the stored value unchanged. `null` clears it. A value replaces it. It can arrive + after the message starts streaming. + """ + content: Optional[ List[ Annotated[ Union[ @@ -4541,32 +4828,33 @@ class CompactionUpdate(BaseModel): ] ] = None """ - Complete replacement user-displayable summary retained by the compaction. - """ - error: Optional[str] = None - """ - Human-readable description of why the compaction failed. + Omitted leaves content unchanged. `null` or `[]` clears it. + A non-empty array replaces all content. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ - Extensible metadata patch for this compaction. + Omitted leaves metadata unchanged. `null` removes it. + + Implementations MUST NOT make assumptions about values in `_meta`. """ - @field_validator("error", mode="wrap") + @field_validator( + "recipient_message_id", "recipient_session_id", "sender_message_id", "sender_session_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) - @field_validator("summary", mode="wrap") + @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 CompactionSummaryChunk(BaseModel): - compaction_id: Annotated[str, Field(alias="compactionId")] +class SessionMessageChunk(BaseModel): + message_id: Annotated[str, Field(alias="messageId")] """ - ID of the compaction whose summary receives this content. + Identifier of this message within the enclosing session's transcript. """ content: Annotated[ Union[ @@ -4575,125 +4863,249 @@ class CompactionSummaryChunk(BaseModel): Field(discriminator="type"), ] """ - One content block to append. + A single content block appended to the message. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ - Metadata scoped to this chunk. Omission and `null` both mean absent. + Optional and nullable chunk-scoped metadata. Omitted or `null` means none. + + Implementations MUST NOT make assumptions about values in `_meta`. """ -class SessionMessage(BaseModel): - message_id: Annotated[str, Field(alias="messageId")] +class ClientSessionCapabilities(BaseModel): + compaction: Optional[CompactionCapabilities] = None """ - Identifier of this message within the enclosing session's transcript. + Support for ID-addressed context compaction updates. Omitted or `null` + means unsupported. `{}` advertises the complete compaction contract. """ - sender_session_id: Annotated[Optional[str], Field(alias="senderSessionId")] = None + config_options: Annotated[Optional[SessionConfigOptionsCapabilities], Field(alias="configOptions")] = None + """ + Config option capabilities supported by the client. + + Omitted or `null` both mean the client does not advertise support for any + config option extensions. """ - Optional sending session identity; omission or `null` retains a known value. + notices: Optional[NoticeCapabilities] = None """ - recipient_session_id: Annotated[Optional[str], Field(alias="recipientSessionId")] = None + Support for live user-facing `notice` session updates. + + Optional. Omitted or `null` both mean the client does not advertise support. + Supplying `{}` means the client can present notices to the user. """ - Optional receiving session identity; omission or `null` retains a known value. + prompt_suggestions: Annotated[Optional[PromptSuggestionsCapabilities], Field(alias="promptSuggestions")] = None """ - content: Optional[ - List[ - Annotated[ - Union[ - TextContentBlock, - ImageContentBlock, - AudioContentBlock, - ResourceContentBlock, - EmbeddedResourceContentBlock, - ], - Field(discriminator="type"), - ] - ] - ] = None + **UNSTABLE** + + This capability is not part of the spec yet, and may be removed or changed at any point. + + Support for `prompt_suggestions_update` session updates. + + Optional. Omitted or `null` both mean the client does not advertise support. + Supplying `{}` means the client can offer prompt suggestions made of + `text` and `resource_link` content blocks. """ - Omitted leaves content unchanged; `null` or `[]` clears it. - A non-empty array replaces all content. + cursors: Optional[SessionCursorsCapabilities] = None + """ + **UNSTABLE** + + This capability is not part of the spec yet, and may be removed or changed at any point. + + Support for `cursor_update` session updates. + + Optional. Omitted or `null` both mean the client does not advertise support. + Supplying `{}` means the client handles `cursor_update`. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ - Omitted leaves metadata unchanged; `null` removes it. + The _meta property is reserved by ACP to allow clients and agents to attach additional + metadata to their interactions. Implementations MUST NOT make assumptions about values at + these keys. - Implementations MUST NOT make assumptions about values in `_meta`. + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - @field_validator("recipient_session_id", "sender_session_id", mode="wrap") + @field_validator("compaction", "config_options", "cursors", "notices", "prompt_suggestions", 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", mode="wrap") - @classmethod - def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) -> Any: - return skip_invalid_items(v, handler, info) - -class SessionMessageChunk(BaseModel): - message_id: Annotated[str, Field(alias="messageId")] +class SystemPrompt(BaseModel): + mode: Union[Literal["append"], Literal["override"], str] """ - Identifier of this message within the enclosing session's transcript. + How the Agent combines `content` with its own instructions. + + Required. Agents MUST return an error for a mode they do not support rather than + treating it as `append` or `override`. """ - sender_session_id: Annotated[Optional[str], Field(alias="senderSessionId")] = None + content: List[ + Annotated[ + Union[ + TextContentBlock, + ImageContentBlock, + AudioContentBlock, + ResourceContentBlock, + EmbeddedResourceContentBlock, + ], + Field(discriminator="type"), + ] + ] """ - Optional sending session identity; omission or `null` retains a known value. + The system prompt content. + + Agents advertising the capability MUST accept `text` content blocks. + Clients MUST NOT send other content block types until a future + capability allows them, and Agents MUST return an error for content + blocks they do not support. + + Clients MUST NOT send an empty array. Agents MAY reject one with + `-32602` without creating, loading, or resuming the session. """ - recipient_session_id: Annotated[Optional[str], Field(alias="recipientSessionId")] = None + field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ - Optional receiving session identity; omission or `null` retains a known value. + The _meta property is reserved by ACP to allow clients and agents to attach additional + metadata to their interactions. Implementations MUST NOT make assumptions about values at + these keys. + + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - content: Annotated[ - Union[ - TextContentBlock, ImageContentBlock, AudioContentBlock, ResourceContentBlock, EmbeddedResourceContentBlock - ], - Field(discriminator="type"), + + +class LoadSessionRequest(BaseModel): + mcp_servers: Annotated[ + List[Union[HttpMcpServer, SseMcpServer, AcpMcpServer, McpServerStdio]], Field(alias="mcpServers") ] """ - A single content block appended to the message. + List of MCP servers to connect to for this session. """ - field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None + cwd: str + """ + The working directory for this session. Must be an absolute path. + """ + additional_directories: Annotated[Optional[List[str]], Field(alias="additionalDirectories")] = None """ - Optional and nullable chunk-scoped metadata; omitted or `null` means none. + Additional workspace roots to activate for this session. Each path must be absolute. - Implementations MUST NOT make assumptions about values in `_meta`. + When omitted or empty, no additional roots are activated. When non-empty, + this is the complete resulting additional-root list for the loaded + session. It may differ from any previously used or reported list as long as + the request `cwd` matches the session's `cwd`. + """ + session_id: Annotated[str, Field(alias="sessionId")] + """ + The ID of the session to load. + """ + system_prompt: Annotated[Optional[SystemPrompt], Field(alias="systemPrompt")] = None """ + System-level instructions for the loaded session. - @field_validator("recipient_session_id", "sender_session_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) + Optional. Omitted and `null` are equivalent. The Agent may then keep a + system prompt it stored with the session or use its default instructions. + Clients MUST only send this when the Agent advertises + `sessionCapabilities.systemPrompt`, and SHOULD send the same value they used + when the session was created. + """ + config_options: Annotated[ + Optional[List[Union[InitialSessionConfigOption1, InitialSessionConfigOption2]]], Field(alias="configOptions") + ] = None + """ + **UNSTABLE** + This capability is not part of the spec yet, and may be removed or changed at any point. -class ClientSessionCapabilities(BaseModel): - compaction: Optional[CompactionCapabilities] = None + Initial values for the session's config options. + + Optional. Omitted and `null` are equivalent to an empty list. Clients MUST only send + this when the Agent advertises `sessionCapabilities.options`. + + The Agent applies the entries in list order, as if the Client had called + `session/set_config_option` for each entry after the session was set up. Malformed + entries and duplicate `configId` values fail the request with `-32602`. The Agent MUST + ignore an entry whose `configId` is unknown, whose `type` does not match the option, + or whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually + has. The Agent SHOULD NOT send `config_option_update` notifications for these entries. + """ + 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/v1/draft/extensibility) + """ + + +class ForkSessionRequest(BaseModel): + session_id: Annotated[str, Field(alias="sessionId")] + """ + The ID of the session to fork. + """ + cursor_id: Annotated[Optional[str], Field(alias="cursorId")] = None """ **UNSTABLE** This capability is not part of the spec yet, and may be removed or changed at any point. - Support for ID-addressed context compaction updates. Omitted or `null` - means unsupported; `{}` advertises the complete compaction contract. + The session cursor to fork at. The new session's history is the source + session's history before the cursor. + + Optional. Omitted and `null` are equivalent and fork the whole session. + Clients MUST only send the ID of a cursor that the Agent announced on the + source session and that currently advertises `capabilities.fork`. The Agent + rejects any other ID with `-32602`. It does not fall back to forking the + whole session. """ - config_options: Annotated[Optional[SessionConfigOptionsCapabilities], Field(alias="configOptions")] = None + cwd: str """ - Config option capabilities supported by the client. + 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. - Omitted or `null` both mean the client does not advertise support for any - config option extensions. + When omitted or empty, no additional roots are activated. When non-empty, + this is the complete resulting additional-root list for the forked + session. """ - notices: Optional[NoticeCapabilities] = None + mcp_servers: Annotated[ + Optional[List[Union[HttpMcpServer, SseMcpServer, AcpMcpServer, McpServerStdio]]], Field(alias="mcpServers") + ] = None + """ + List of MCP servers to connect to for this session. + """ + system_prompt: Annotated[Optional[SystemPrompt], Field(alias="systemPrompt")] = None + """ + System-level instructions for the forked session. + + Optional. Omitted and `null` are equivalent. The Agent may then keep a + system prompt it stored with the source session or use its default + instructions. Clients MUST only send this when the Agent advertises + `sessionCapabilities.systemPrompt`, and SHOULD send the same value they used + for the source session. + """ + config_options: Annotated[ + Optional[List[Union[InitialSessionConfigOption1, InitialSessionConfigOption2]]], Field(alias="configOptions") + ] = None """ **UNSTABLE** This capability is not part of the spec yet, and may be removed or changed at any point. - Support for live advisory `notice` session updates. + Initial values for the forked session's config options. - Optional. Omitted or `null` both mean the client does not advertise support. - Supplying `{}` means the client can present notices to the user. + Optional. Omitted and `null` are equivalent to an empty list. Clients MUST only send + this when the Agent advertises `sessionCapabilities.options`. + + The Agent applies the entries in list order on top of the configuration the fork + starts with, as if the Client had called `session/set_config_option` for each entry + after the session was set up. Malformed entries and duplicate `configId` values fail + the request with `-32602`. The Agent MUST ignore an entry whose `configId` is unknown, + whose `type` does not match the option, or whose value is not allowed when it is + applied. The `configOptions` in the response contain the values the session actually + has. The Agent SHOULD NOT send `config_option_update` notifications for these entries, + and SHOULD NOT send other `session/update` notifications caused by applying them + before it responds. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -4701,33 +5113,63 @@ class ClientSessionCapabilities(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - @field_validator("compaction", "config_options", "notices", 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 NewSessionRequest(BaseModel): +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 for this session. Each path must be absolute. + Additional workspace roots to activate for this session. Each path must be absolute. - These expand the session's filesystem scope without changing `cwd`, which - remains the base for relative paths. When omitted or empty, no - additional roots are activated for the new session. + When omitted or empty, no additional roots are activated. When non-empty, + this is the complete resulting additional-root list for the 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[ - List[Union[HttpMcpServer, SseMcpServer, AcpMcpServer, McpServerStdio]], Field(alias="mcpServers") - ] + Optional[List[Union[HttpMcpServer, SseMcpServer, AcpMcpServer, McpServerStdio]]], Field(alias="mcpServers") + ] = None """ - List of MCP (Model Context Protocol) servers the agent should connect to. + List of MCP servers to connect to for this session. + """ + system_prompt: Annotated[Optional[SystemPrompt], Field(alias="systemPrompt")] = None + """ + System-level instructions for the resumed session. + + Optional. Omitted and `null` are equivalent. The Agent may then keep a + system prompt it stored with the session or use its default instructions. + Clients MUST only send this when the Agent advertises + `sessionCapabilities.systemPrompt`, and SHOULD send the same value they used + when the session was created. + """ + config_options: Annotated[ + Optional[List[Union[InitialSessionConfigOption1, InitialSessionConfigOption2]]], Field(alias="configOptions") + ] = None + """ + **UNSTABLE** + + This capability is not part of the spec yet, and may be removed or changed at any point. + + Initial values for the session's config options. + + Optional. Omitted and `null` are equivalent to an empty list. Clients MUST only send + this when the Agent advertises `sessionCapabilities.options`. + + The Agent applies the entries in list order, as if the Client had called + `session/set_config_option` for each entry after the session was set up. Malformed + entries and duplicate `configId` values fail the request with `-32602`. The Agent MUST + ignore an entry whose `configId` is unknown, whose `type` does not match the option, + or whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually + has. The Agent SHOULD NOT send `config_option_update` notifications for these entries. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -4735,14 +5177,9 @@ class NewSessionRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/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 PromptRequest(BaseModel): session_id: Annotated[str, Field(alias="sessionId")] @@ -4764,15 +5201,15 @@ class PromptRequest(BaseModel): """ 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`]. + As a baseline, the Agent MUST support `text` and `resource_link` content blocks, + while other variants are optionally enabled via `PromptCapabilities`. - The Client MUST adapt its interface according to [`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`]. + `resource` or `resource_link` content blocks. - When available, [`ContentBlock::Resource`] is preferred + When available, `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. """ @@ -4782,42 +5219,7 @@ class PromptRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -4832,41 +5234,9 @@ class RequestPermissionResponse(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - """ - - -class DidChangeDocumentNotification(BaseModel): - session_id: Annotated[str, Field(alias="sessionId")] - """ - The session ID for this notification. - """ - uri: str - """ - 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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/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" @@ -4922,7 +5292,7 @@ class ElicitationSchema(BaseModel): Optional. Omitted and `null` are equivalent and mean no metadata. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("description", "title", "type", mode="wrap") @@ -4952,10 +5322,115 @@ class ElicitationFormMode(RootModel[Union[ElicitationFormSessionMode, Elicitatio """ -class NesEventCapabilities(BaseModel): - document: Optional[NesDocumentEventCapabilities] = None +class SessionCapabilities(BaseModel): + list: Optional[SessionListCapabilities] = None + """ + Whether the agent supports `session/list`. + + Optional. Omitted or `null` both mean the agent does not advertise support. + Supplying `{}` means the agent supports listing 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 that also support `session/list` may return + `SessionInfo.additionalDirectories` to report the complete ordered + additional-root list associated with a listed session. + """ + system_prompt: Annotated[Optional[SessionSystemPromptCapabilities], Field(alias="systemPrompt")] = None + """ + Whether the agent supports `systemPrompt` on session lifecycle requests. + + Optional. Omitted or `null` both mean the agent does not advertise support. + Supplying `{}` means the agent supports `systemPrompt` in `append` mode. + """ + 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. + """ + archive: Optional[SessionArchiveCapabilities] = 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/archive` and `session/unarchive`. + + Optional. Omitted or `null` both mean the agent does not advertise support. + Supplying `{}` means the agent supports both methods, the `archived` filter on + `session/list`, and `SessionInfo.archived`. Agents that advertise it MUST also advertise `sessionCapabilities.list`. + """ + status: Optional[SessionStatusCapabilities] = 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/status`. + + Optional. Omitted or `null` both mean the agent does not advertise support. + Supplying `{}` means the agent supports checking session status. + """ + options: Optional[SessionOptionsCapabilities] = 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/options`. + + Optional. Omitted or `null` both mean the agent does not advertise support. + Supplying `{}` means the agent supports `session/options` and accepts initial + config option values on session setup requests. + """ + title: Optional[SessionTitleCapabilities] = 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/set_title`. + + Agents report titles through `session/list` and `session_info_update` without this + capability. It only advertises that Clients can set titles. + + Optional. Omitted or `null` both mean the agent does not advertise support. + Supplying `{}` means the agent supports setting session titles. + """ + resume: Optional[SessionResumeCapabilities] = None + """ + Whether the agent supports `session/resume`. + + Optional. Omitted or `null` both mean the agent does not advertise support. + Supplying `{}` means the agent supports resuming sessions. + """ + close: Optional[SessionCloseCapabilities] = None """ - Document event capabilities. + Whether the agent supports `session/close`. + + Optional. Omitted or `null` both mean the agent does not advertise support. + Supplying `{}` means the agent supports closing sessions. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -4963,10 +5438,23 @@ class NesEventCapabilities(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - @field_validator("document", mode="wrap") + @field_validator( + "additional_directories", + "archive", + "close", + "delete", + "fork", + "list", + "options", + "resume", + "status", + "system_prompt", + "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) @@ -4986,7 +5474,9 @@ class SessionConfigOptionSelect(SessionConfigSelect): Optional description for the Client to display to the user. """ category: Optional[ - Union[Literal["mode"], Literal["model"], Literal["model_config"], Literal["thought_level"], str] + Union[ + Literal["mode"], Literal["model"], Literal["model_config"], Literal["speed"], Literal["thought_level"], str + ] ] = None """ Optional semantic category for this option (UX only). @@ -4997,7 +5487,7 @@ class SessionConfigOptionSelect(SessionConfigSelect): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ type: Literal["select"] = "select" @@ -5007,7 +5497,7 @@ class LoadSessionResponse(BaseModel): """ Initial mode state if supported by the Agent - See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes) + See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/draft/session-modes) """ config_options: Annotated[ Optional[ @@ -5024,7 +5514,7 @@ class LoadSessionResponse(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("modes", mode="wrap") @@ -5047,7 +5537,7 @@ class ForkSessionResponse(BaseModel): """ Initial mode state if supported by the Agent - See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes) + See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/draft/session-modes) """ config_options: Annotated[ Optional[ @@ -5064,7 +5554,46 @@ class ForkSessionResponse(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) + """ + + @field_validator("modes", 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("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 SessionOptionsResponse(BaseModel): + modes: Optional[SessionModeState] = None + """ + The mode state the session would start with, if the Agent supports modes. + + See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/draft/session-modes) + """ + config_options: Annotated[ + Optional[ + List[Annotated[Union[SessionConfigOptionSelect, SessionConfigOptionBoolean], Field(discriminator="type")]] + ], + Field(alias="configOptions"), + ] = None + """ + The config options the session would start with, with the same rules as on + `NewSessionResponse`. + + Optional. Omitted, `null`, or empty means no config options are advertised. + """ + 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/v1/draft/extensibility) """ @field_validator("modes", mode="wrap") @@ -5083,7 +5612,7 @@ class ResumeSessionResponse(BaseModel): """ Initial mode state if supported by the Agent - See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes) + See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/draft/session-modes) """ config_options: Annotated[ Optional[ @@ -5100,7 +5629,7 @@ class ResumeSessionResponse(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("modes", mode="wrap") @@ -5128,7 +5657,7 @@ class SetSessionConfigOptionResponse(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("config_options", mode="wrap") @@ -5137,10 +5666,6 @@ def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHand 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" @@ -5178,6 +5703,16 @@ class SessionUpdateCompactionSummaryChunk(CompactionSummaryChunk): ) +class SessionUpdatePromptSuggestionsUpdate(PromptSuggestionsUpdate): + session_update: Annotated[Literal["prompt_suggestions_update"], Field(alias="sessionUpdate")] = ( + "prompt_suggestions_update" + ) + + +class SessionUpdateSubagentUpdate(SubagentUpdate): + session_update: Annotated[Literal["subagent_update"], Field(alias="sessionUpdate")] = "subagent_update" + + class SessionUpdateSessionMessage(SessionMessage): session_update: Annotated[Literal["session_message"], Field(alias="sessionUpdate")] = "session_message" @@ -5216,7 +5751,7 @@ class ToolCall(BaseModel): content: Optional[ List[ Annotated[ - Union[ContentToolCallContent, FileEditToolCallContent, TerminalToolCallContent], + Union[ContentToolCallContent, FileEditToolCallContent, TerminalToolCallContent, ToolCallContentSession], Field(discriminator="type"), ] ] @@ -5243,7 +5778,7 @@ class ToolCall(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("kind", "name", "raw_input", "raw_output", "status", mode="wrap") @@ -5271,7 +5806,7 @@ class ConfigOptionUpdateBase(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -5333,75 +5868,69 @@ class ClientCapabilities(BaseModel): 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/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - @field_validator("auth", "elicitation", "fs", "nes", "plan", "session", "subagents", "terminal", mode="wrap") + @field_validator("auth", "elicitation", "fs", "plan", "session", "subagents", "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) - @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 SuggestNesRequest(BaseModel): - session_id: Annotated[str, Field(alias="sessionId")] - """ - The session ID for this request. - """ - uri: str - """ - The URI of the document to suggest for. - """ - version: int +class NewSessionRequest(BaseModel): + cwd: str """ - The version number of the document. + The working directory for this session. Must be an absolute path. """ - position: Position + additional_directories: Annotated[Optional[List[str]], Field(alias="additionalDirectories")] = None """ - The current cursor position. + Additional workspace roots for this session. Each path must be absolute. + + These expand the session's filesystem scope without changing `cwd`, which + remains the base for relative paths. When omitted or empty, no + additional roots are activated for the new session. """ - selection: Optional[Range] = None + mcp_servers: Annotated[ + List[Union[HttpMcpServer, SseMcpServer, AcpMcpServer, McpServerStdio]], Field(alias="mcpServers") + ] """ - The current text selection range, if any. + List of MCP (Model Context Protocol) servers the agent should connect to. """ - trigger_kind: Annotated[Literal["automatic", "diagnostic", "manual"], Field(alias="triggerKind")] + system_prompt: Annotated[Optional[SystemPrompt], Field(alias="systemPrompt")] = None """ - What triggered this suggestion request. + System-level instructions for the new session. + + Optional. Omitted and `null` are equivalent and mean the Agent uses its + own default instructions. Clients MUST only send this when the Agent + advertises `sessionCapabilities.systemPrompt`. """ - context: Optional[NesSuggestContext] = None + config_options: Annotated[ + Optional[List[Union[InitialSessionConfigOption1, InitialSessionConfigOption2]]], Field(alias="configOptions") + ] = None """ - Context for the suggestion, included based on agent capabilities. + **UNSTABLE** + + This capability is not part of the spec yet, and may be removed or changed at any point. + + Initial values for the session's config options. + + Optional. Omitted and `null` are equivalent to an empty list. Clients MUST only send + this when the Agent advertises `sessionCapabilities.options`. + + The Agent applies the entries in list order, as if the Client had called + `session/set_config_option` for each entry after the session was set up. Malformed + entries and duplicate `configId` values fail the request with `-32602`. The Agent MUST + ignore an entry whose `configId` is unknown, whose `type` does not match the option, + or whose value is not allowed when it is applied. The `configOptions` in the response contain the values the session actually + has. The Agent SHOULD NOT send `config_option_update` notifications for these entries, + and SHOULD NOT send other `session/update` notifications caused by applying them + before it responds. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -5409,7 +5938,7 @@ class SuggestNesRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -5427,45 +5956,23 @@ class ClientResponseMessage(BaseModel): ReleaseTerminalResponse, WaitForTerminalExitResponse, KillTerminalResponse, - Union[ - AcceptElicitationResponse, DeclineElicitationResponse, CancelElicitationResponse, OtherElicitationResponse - ], - Union[McpResultResponse, McpErrorResponse], + AcceptElicitationResponse, + DeclineElicitationResponse, + CancelElicitationResponse, + OtherElicitationResponse, + McpResultResponse, + McpErrorResponse, 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[ - CancelNotification, - DidOpenDocumentNotification, - DidChangeDocumentNotification, - DidCloseDocumentNotification, - DidSaveDocumentNotification, - DidFocusDocumentNotification, - AcceptNesNotification, - RejectNesNotification, - MessageMcpNotification, - Any, - ] - ] = None + Method-specific response data. """ - Method-specific notification parameters. + + +class ClientResponse(RootModel[Union[ClientResponseMessage, ClientErrorMessage]]): + root: Union[ClientResponseMessage, ClientErrorMessage] + """ + A JSON-RPC response object. """ @@ -5498,7 +6005,7 @@ class ToolCallUpdate(BaseModel): content: Optional[ List[ Annotated[ - Union[ContentToolCallContent, FileEditToolCallContent, TerminalToolCallContent], + Union[ContentToolCallContent, FileEditToolCallContent, TerminalToolCallContent, ToolCallContentSession], Field(discriminator="type"), ] ] @@ -5524,7 +6031,7 @@ class ToolCallUpdate(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("kind", "name", "raw_input", "raw_output", "status", "title", mode="wrap") @@ -5565,7 +6072,7 @@ class CreateFormSessionElicitationRequest(CreateFormSessionElicitationRequestBas Optional. Omitted and `null` are equivalent and mean no metadata. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ mode: Literal["form"] = "form" @@ -5583,19 +6090,50 @@ class CreateFormRequestElicitationRequest(CreateFormRequestElicitationRequestBas Optional. Omitted and `null` are equivalent and mean no metadata. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ mode: Literal["form"] = "form" -class NesCapabilities(BaseModel): - events: Optional[NesEventCapabilities] = None +class AgentCapabilities(BaseModel): + load_session: Annotated[Optional[bool], Field(alias="loadSession")] = False + """ + Whether the agent supports `session/load`. + """ + prompt_capabilities: Annotated[ + Optional[PromptCapabilities], Field(alias="promptCapabilities", validate_default=True) + ] = {"image": False, "audio": False, "embeddedContext": False} + """ + Prompt capabilities supported by the agent. + """ + mcp_capabilities: Annotated[Optional[McpCapabilities], Field(alias="mcpCapabilities", validate_default=True)] = { + "http": False, + "sse": False, + "acp": False, + } + """ + MCP capabilities supported by the agent. + """ + session_capabilities: Annotated[ + Optional[SessionCapabilities], Field(alias="sessionCapabilities", validate_default=True) + ] = {} + """ + Session lifecycle and prompt capabilities advertised by the agent. + """ + auth: Annotated[Optional[AgentAuthCapabilities], Field(validate_default=True)] = {} """ - Events the agent wants to receive. + Authentication-related capabilities supported by the agent. """ - context: Optional[NesContextCapabilities] = None + providers: Optional[ProvidersCapabilities] = None """ - Context the agent wants attached to each suggestion request. + **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. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -5603,10 +6141,18 @@ class NesCapabilities(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - @field_validator("context", "events", mode="wrap") + @field_validator( + "auth", + "load_session", + "mcp_capabilities", + "prompt_capabilities", + "providers", + "session_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) @@ -5623,7 +6169,7 @@ class NewSessionResponse(BaseModel): """ Initial mode state if supported by the Agent - See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes) + See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/v1/draft/session-modes) """ config_options: Annotated[ Optional[ @@ -5640,7 +6186,7 @@ class NewSessionResponse(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("modes", mode="wrap") @@ -5654,31 +6200,6 @@ def skip_invalid_items_validator(cls, v: Any, handler: ValidatorFunctionWrapHand return skip_invalid_items(v, handler, info) -class SuggestNesResponse(BaseModel): - suggestions: List[ - Annotated[ - Union[ - NesEditSuggestionVariant, - NesJumpSuggestionVariant, - NesRenameSuggestionVariant, - NesSearchAndReplaceSuggestionVariant, - ], - Field(discriminator="kind"), - ] - ] - """ - 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/extensibility) - """ - - class ToolCallStart(ToolCall): session_update: Annotated[Literal["tool_call"], Field(alias="sessionUpdate")] = "tool_call" @@ -5703,11 +6224,7 @@ class InitializeRequest(BaseModel): """ client_capabilities: Annotated[ Optional[ClientCapabilities], Field(alias="clientCapabilities", validate_default=True) - ] = { - "fs": {"readTextFile": False, "writeTextFile": False}, - "terminal": False, - "auth": {"terminal": False}, - } + ] = {"fs": {"readTextFile": False, "writeTextFile": False}, "terminal": False, "auth": {"terminal": False}} """ Capabilities supported by the client. """ @@ -5723,7 +6240,7 @@ class InitializeRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @field_validator("protocol_version", mode="before") @@ -5737,6 +6254,10 @@ def use_default_on_error_validator(cls, v: Any, handler: ValidatorFunctionWrapHa return use_default_on_error(v, handler, info) +class InitializeProxyRequest(InitializeRequest): + pass + + class RequestPermissionRequest(BaseModel): session_id: Annotated[str, Field(alias="sessionId")] """ @@ -5756,72 +6277,41 @@ class RequestPermissionRequest(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ -class AgentCapabilities(BaseModel): - load_session: Annotated[Optional[bool], Field(alias="loadSession")] = False +class InitializeResponse(BaseModel): + protocol_version: Annotated[int, Field(alias="protocolVersion", ge=0, le=65535)] """ - Whether the agent supports `session/load`. + 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. """ - prompt_capabilities: Annotated[ - Optional[PromptCapabilities], Field(alias="promptCapabilities", validate_default=True) + agent_capabilities: Annotated[ + Optional[AgentCapabilities], Field(alias="agentCapabilities", validate_default=True) ] = { - "image": False, - "audio": False, - "embeddedContext": False, - } - """ - Prompt capabilities supported by the agent. - """ - mcp_capabilities: Annotated[Optional[McpCapabilities], Field(alias="mcpCapabilities", validate_default=True)] = { - "http": False, - "sse": False, - "acp": False, + "loadSession": False, + "promptCapabilities": {"image": False, "audio": False, "embeddedContext": False}, + "mcpCapabilities": {"http": False, "sse": False, "acp": False}, + "sessionCapabilities": {}, + "auth": {}, } """ - MCP capabilities supported by the agent. - """ - session_capabilities: Annotated[ - Optional[SessionCapabilities], Field(alias="sessionCapabilities", validate_default=True) - ] = {} - """ - Session lifecycle and prompt capabilities advertised by the agent. - """ - auth: Annotated[Optional[AgentAuthCapabilities], Field(validate_default=True)] = {} - """ - Authentication-related capabilities supported by the agent. - """ - 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. + Capabilities supported by the agent. """ - nes: Optional[NesCapabilities] = None + auth_methods: Annotated[ + Optional[List[Union[TerminalAuthMethod, AuthMethodAgent]]], Field(alias="authMethods", validate_default=True) + ] = [] """ - **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. + Authentication methods supported by the agent. """ - position_encoding: Annotated[Optional[Literal["utf-16", "utf-32", "utf-8"]], Field(alias="positionEncoding")] = None + agent_info: Annotated[Optional[Implementation], Field(alias="agentInfo")] = None """ - **UNSTABLE** - - This capability is not part of the spec yet, and may be removed or changed at any point. + Information about the Agent name and version sent to the Client. - The position encoding selected by the agent from the client's supported encodings. + Note: in future versions of the protocol, this will be required. """ field_meta: Annotated[Optional[Dict[str, Any]], Field(alias="_meta")] = None """ @@ -5829,24 +6319,19 @@ class AgentCapabilities(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ - @field_validator( - "auth", - "load_session", - "mcp_capabilities", - "nes", - "position_encoding", - "prompt_capabilities", - "providers", - "session_capabilities", - mode="wrap", - ) + @field_validator("agent_capabilities", "agent_info", 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 SessionNotification(BaseModel): session_id: Annotated[str, Field(alias="sessionId")] @@ -5871,6 +6356,8 @@ class SessionNotification(BaseModel): SessionUpdateNotice, SessionUpdateCompactionUpdate, SessionUpdateCompactionSummaryChunk, + SessionUpdatePromptSuggestionsUpdate, + SessionUpdateCursorUpdate, SessionUpdateSubagentUpdate, SessionUpdateSessionMessage, SessionUpdateSessionMessageChunk, @@ -5886,7 +6373,7 @@ class SessionNotification(BaseModel): metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. - See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) + See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/draft/extensibility) """ @@ -5907,19 +6394,23 @@ class ClientRequest(BaseModel): SetProviderRequest, DisableProviderRequest, LogoutRequest, + AuthStatusRequest, NewSessionRequest, LoadSessionRequest, ListSessionsRequest, DeleteSessionRequest, ForkSessionRequest, + ArchiveSessionRequest, + UnarchiveSessionRequest, + SessionStatusRequest, + SessionOptionsRequest, + SetSessionTitleRequest, ResumeSessionRequest, CloseSessionRequest, SetSessionModeRequest, PromptRequest, - StartNesRequest, - SuggestNesRequest, - CloseNesRequest, - Union[SetSessionConfigOptionBooleanRequest, SetSessionConfigOptionSelectRequest], + SetSessionConfigOptionBooleanRequest, + SetSessionConfigOptionSelectRequest, Any, ] ] = None @@ -5928,6 +6419,25 @@ class ClientRequest(BaseModel): """ +class ProxyRequest(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[InitializeProxyRequest, ProxySuccessorRequest]] = None + """ + Method-specific request parameters. + """ + + +class InitializeProxyResponse(InitializeResponse): + pass + + class AgentRequest(BaseModel): id: Optional[Union[int, str]] """ @@ -5948,11 +6458,12 @@ class AgentRequest(BaseModel): WaitForTerminalExitRequest, KillTerminalRequest, MessageMcpRequest, - Union[ - Union[CreateOtherSessionElicitationRequest, CreateOtherRequestElicitationRequest], - Union[CreateFormSessionElicitationRequest, CreateFormRequestElicitationRequest], - Union[CreateUrlSessionElicitationRequest, CreateUrlRequestElicitationRequest], - ], + CreateOtherSessionElicitationRequest, + CreateOtherRequestElicitationRequest, + CreateFormSessionElicitationRequest, + CreateFormRequestElicitationRequest, + CreateUrlSessionElicitationRequest, + CreateUrlRequestElicitationRequest, Any, ] ] = None @@ -5961,69 +6472,6 @@ class AgentRequest(BaseModel): """ -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. - """ - agent_capabilities: Annotated[ - Optional[AgentCapabilities], Field(alias="agentCapabilities", validate_default=True) - ] = { - "loadSession": False, - "promptCapabilities": {"image": False, "audio": False, "embeddedContext": False}, - "mcpCapabilities": {"http": False, "sse": False, "acp": False}, - "sessionCapabilities": {}, - "auth": {}, - } - """ - Capabilities supported by the agent. - """ - auth_methods: Annotated[ - Optional[List[Union[TerminalAuthMethod, AuthMethodAgent]]], Field(alias="authMethods", validate_default=True) - ] = [] - """ - Authentication methods supported by the agent. - """ - agent_info: Annotated[Optional[Implementation], Field(alias="agentInfo")] = None - """ - Information about the Agent name and version sent to the Client. - - Note: in future versions of the protocol, this will be 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/extensibility) - """ - - @field_validator("agent_capabilities", "agent_info", 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[SessionNotification, CompleteElicitationNotification, Any]] = None - """ - Method-specific notification parameters. - """ - - class AgentResponseMessage(BaseModel): id: Optional[Union[int, str]] """ @@ -6036,19 +6484,22 @@ class AgentResponseMessage(BaseModel): SetProviderResponse, DisableProviderResponse, LogoutResponse, + AuthStatusResponse, NewSessionResponse, LoadSessionResponse, ListSessionsResponse, DeleteSessionResponse, ForkSessionResponse, + ArchiveSessionResponse, + UnarchiveSessionResponse, + SessionStatusResponse, + SessionOptionsResponse, + SetSessionTitleResponse, ResumeSessionResponse, CloseSessionResponse, SetSessionModeResponse, SetSessionConfigOptionResponse, PromptResponse, - StartNesResponse, - SuggestNesResponse, - CloseNesResponse, Any, ] """ @@ -6063,6 +6514,37 @@ class AgentResponse(RootModel[Union[AgentResponseMessage, AgentErrorMessage]]): """ +class AgentNotification(BaseModel): + method: str + """ + The notification method name. + """ + params: Optional[Union[SessionNotification, CompleteElicitationNotification, AuthStatusUpdateNotification, Any]] = ( + None + ) + """ + Method-specific notification parameters. + """ + + +class ProxyResponse1(BaseModel): + id: Optional[Union[int, str]] + """ + The id of the request this response answers. + """ + result: Union[InitializeProxyResponse, Any] + """ + Method-specific response data. + """ + + +class ProxyResponse(RootModel[Union[ProxyResponse1, ProxyResponse2]]): + root: Union[ProxyResponse1, ProxyResponse2] + """ + A JSON-RPC response object. + """ + + MessageMcpResponse = Annotated[Union[McpResultResponse, McpErrorResponse], Field(union_mode="left_to_right")] PermissionOptionKind = Literal["allow_once", "allow_always", "reject_once", "reject_always"] diff --git a/tests/conftest.py b/tests/conftest.py index 61933534..39ac9331 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -137,6 +137,7 @@ def __init__(self) -> None: self.notifications: list[SessionNotification] = [] self.elicitation_requests: list[tuple[str, ElicitationMode, dict[str, Any]]] = [] self.completed_elicitations: list[CompleteElicitationNotification] = [] + self.auth_status_updates: list[dict[str, Any]] = [] self.ext_calls: list[tuple[str, dict]] = [] self.ext_notes: list[tuple[str, dict]] = [] self._agent_conn = None @@ -235,6 +236,9 @@ async def complete_elicitation(self, elicitation_id: str, **kwargs: Any) -> None CompleteElicitationNotification(elicitation_id=elicitation_id, field_meta=kwargs or None) ) + async def auth_status_update(self, state: str, accounts: list[Any] | None = None, **kwargs: Any) -> None: + self.auth_status_updates.append({"state": state, "accounts": accounts, **kwargs}) + async def mcp_message( self, server_id: str, request_id: str, method: str, params: dict[str, Any] | None = None, **kwargs: Any ) -> Any: diff --git a/tests/test_deserialize.py b/tests/test_deserialize.py index 42188ffa..b08c2d5e 100644 --- a/tests/test_deserialize.py +++ b/tests/test_deserialize.py @@ -9,7 +9,7 @@ from pydantic import BaseModel, field_validator from acp._deserialize import salvage_on_error, skip_invalid_items -from acp.schema import ReadTextFileRequest, ToolCallUpdate, WriteTextFileRequest +from acp.schema import ToolCallLocation, ToolCallUpdate, WriteTextFileRequest class _Salvage(BaseModel): @@ -50,9 +50,10 @@ def test_meta_is_salvaged_to_none() -> None: def test_default_on_error_field_is_salvaged() -> None: - salvaged = ReadTextFileRequest.model_validate({"sessionId": "s", "path": "/p", "line": "nan"}) + # Schema 1.33 dropped x-deserialize-default-on-error from ReadTextFileRequest.line; ToolCallLocation.line keeps it. + salvaged = ToolCallLocation.model_validate({"path": "/p", "line": "nan"}) assert salvaged.line is None - kept = ReadTextFileRequest.model_validate({"sessionId": "s", "path": "/p", "line": 5}) + kept = ToolCallLocation.model_validate({"path": "/p", "line": 5}) assert kept.line == 5 diff --git a/tests/test_gen_all.py b/tests/test_gen_all.py index 5a9240d1..ccd4ed81 100644 --- a/tests/test_gen_all.py +++ b/tests/test_gen_all.py @@ -82,12 +82,12 @@ def test_signature_generation_preserves_inline_literal_values() -> None: tree = ast.parse( "from typing import Any\n" - "from schema import SetProviderRequest, SuggestNesRequest\n" + "from schema import SetProviderRequest, StringPropertySchema\n" "class Methods:\n" ' @param_model(SetProviderRequest, method="providers/set", unstable=True)\n' " async def set_provider(self, **kwargs: Any): ...\n" - " @param_model(SuggestNesRequest)\n" - " async def suggest_nes(self, **kwargs: Any): ...\n" + " @param_model(StringPropertySchema)\n" + " async def string_property(self, **kwargs: Any): ...\n" ) NodeTransformer().visit(tree) ast.fix_missing_locations(tree) @@ -106,17 +106,18 @@ def test_signature_generation_preserves_inline_literal_values() -> None: "method": "providers/set", "unstable": True, } - suggest = methods.body[-1] - assert isinstance(suggest, ast.AsyncFunctionDef) - trigger = next(arg for arg in suggest.args.args if arg.arg == "trigger_kind") - annotation = ast.unparse(trigger.annotation) + # Schema 1.33 removed SuggestNesRequest. StringPropertySchema.format is a multi-value Literal with no schema alias. + choose = methods.body[-1] + assert isinstance(choose, ast.AsyncFunctionDef) + fmt = next(arg for arg in choose.args.args + choose.args.kwonlyargs if arg.arg == "format") + annotation = ast.unparse(fmt.annotation) class Annotated: - __annotations__ = {"trigger": annotation} + __annotations__ = {"format": annotation} assert ( - get_type_hints(Annotated, globalns={"Literal": Literal})["trigger"] - == Literal["automatic", "diagnostic", "manual"] + get_type_hints(Annotated, globalns={"Literal": Literal})["format"] + == Literal["email", "uri", "date", "date-time"] | None ) diff --git a/tests/test_protocol_method_coverage.py b/tests/test_protocol_method_coverage.py index 8e059975..9dd09f0e 100644 --- a/tests/test_protocol_method_coverage.py +++ b/tests/test_protocol_method_coverage.py @@ -28,53 +28,22 @@ ), ("disable_provider", "providers/disable", {"provider_id": "p"}, schema.DisableProviderResponse()), ("logout", "logout", {}, schema.LogoutResponse()), - ("start_nes", "nes/start", {"workspace_uri": "file:///workspace"}, schema.StartNesResponse(session_id="n")), + ("archive_session", "session/archive", {"session_id": "s"}, schema.ArchiveSessionResponse()), + ("unarchive_session", "session/unarchive", {"session_id": "s"}, schema.UnarchiveSessionResponse()), + ("session_status", "session/status", {"session_id": "s"}, schema.SessionStatusResponse(status="open")), ( - "suggest_nes", - "nes/suggest", - { - "session_id": "n", - "uri": "file:///a", - "version": 1, - "position": schema.Position(line=0, character=0), - "trigger_kind": "manual", - }, - schema.SuggestNesResponse(suggestions=[]), - ), - ("close_nes", "nes/close", {"session_id": "n"}, schema.CloseNesResponse()), -] -POSITION = schema.Position(line=0, character=0) -NOTIFICATIONS = [ - ("accept_nes", "nes/accept", {"session_id": "n", "id": "edit"}), - ("reject_nes", "nes/reject", {"session_id": "n", "id": "edit", "reason": "rejected"}), - ( - "did_open", - "document/didOpen", - {"session_id": "n", "uri": "file:///a", "language_id": "python", "version": 1, "text": "hello"}, + "session_options", + "session/options", + {"cwd": "/w", "additional_directories": ["/x"], "session_id": "s"}, + schema.SessionOptionsResponse(config_options=[]), ), ( - "did_change", - "document/didChange", - { - "session_id": "n", - "uri": "file:///a", - "version": 2, - "content_changes": [schema.TextDocumentContentChangeEvent(text="world")], - }, - ), - ("did_close", "document/didClose", {"session_id": "n", "uri": "file:///a"}), - ("did_save", "document/didSave", {"session_id": "n", "uri": "file:///a", "text": "world"}), - ( - "did_focus", - "document/didFocus", - { - "session_id": "n", - "uri": "file:///a", - "version": 2, - "position": POSITION, - "visible_range": schema.Range(start=POSITION, end=POSITION), - }, + "set_session_title", + "session/set_title", + {"session_id": "s", "title": "t"}, + schema.SetSessionTitleResponse(title="t"), ), + ("auth_status", "auth/status", {}, schema.AuthStatusResponse(state="authenticated")), ] @@ -95,23 +64,6 @@ async def handle(**kwargs): assert handler.await_args.kwargs.items() >= (params | {"trace": "test"}).items() -@pytest.mark.asyncio -@pytest.mark.parametrize(("name", "wire_method", "params"), NOTIFICATIONS) -async def test_agent_notification_roundtrip(connect, agent, name, wire_method, params): - received = asyncio.Event() - calls = [] - - async def handler(**kwargs): - calls.append(kwargs) - received.set() - - setattr(agent, name, handler) - _, connection = connect(use_unstable_protocol=True) - await getattr(connection, name)(**params, trace="test") - await asyncio.wait_for(received.wait(), 2) - assert calls[0].items() >= (params | {"trace": "test"}).items() - - @pytest.mark.asyncio @pytest.mark.parametrize("result", [None, {}, {"tools": []}, [1, "x"], False, 42]) async def test_mcp_requests_and_notifications_share_method(connect, agent, client, result): @@ -211,3 +163,20 @@ async def handle(**kwargs): _, connection = connect() assert await getattr(connection, name)(**params) == response handler.assert_awaited_once_with(**params) + + +@pytest.mark.asyncio +async def test_auth_status_update_reaches_the_client(connect, client): + received = asyncio.Event() + calls: list[dict[str, Any]] = [] + + async def handler(**kwargs: Any) -> None: + calls.append(kwargs) + received.set() + + client.auth_status_update = handler + agent_side, _ = connect(use_unstable_protocol=True) + await agent_side.auth_status_update(state="unauthenticated", trace="test") + await asyncio.wait_for(received.wait(), 2) + assert calls[0]["state"] == "unauthenticated" + assert calls[0]["trace"] == "test" diff --git a/tests/test_sender_parameters.py b/tests/test_sender_parameters.py new file mode 100644 index 00000000..a7888393 --- /dev/null +++ b/tests/test_sender_parameters.py @@ -0,0 +1,23 @@ +"""Every sender puts each of its parameters on the wire. + +`scripts/gen_signature.py` rewrites sender signatures from the schema, but the bodies are hand-written. A field the +schema adds can land in a signature and never reach the request model, and the call then drops it silently. +""" + +import ast +from pathlib import Path + +import pytest + +SRC = Path(__file__).resolve().parents[1] / "src" / "acp" + + +@pytest.mark.parametrize("module", ["client/connection.py", "agent/connection.py"]) +def test_every_sender_uses_all_its_parameters(module: str) -> None: + unused: list[str] = [] + for node in ast.walk(ast.parse((SRC / module).read_text(encoding="utf-8"))): + if isinstance(node, ast.AsyncFunctionDef) and not node.name.startswith("__"): + params = [a.arg for a in node.args.args + node.args.kwonlyargs if a.arg != "self"] + names = {n.id for n in ast.walk(node) if isinstance(n, ast.Name)} + unused += [f"{node.name}({p})" for p in params if p not in names] + assert unused == [] diff --git a/tests/test_session_request_fields.py b/tests/test_session_request_fields.py new file mode 100644 index 00000000..04aed146 --- /dev/null +++ b/tests/test_session_request_fields.py @@ -0,0 +1,39 @@ +"""Session setup requests carry `systemPrompt` to the agent.""" + +import asyncio +import contextlib +from typing import Any + +import pytest + +from acp import schema + + +@pytest.mark.asyncio +@pytest.mark.parametrize( + ("name", "params"), + [ + ("new_session", {"cwd": "/w", "mcp_servers": []}), + ("load_session", {"cwd": "/w", "session_id": "s", "mcp_servers": []}), + ("resume_session", {"cwd": "/w", "session_id": "s", "mcp_servers": []}), + ("fork_session", {"cwd": "/w", "session_id": "s", "mcp_servers": []}), + ], +) +async def test_system_prompt_reaches_the_agent(connect, agent, name, params): + received: list[dict[str, Any]] = [] + done = asyncio.Event() + original = getattr(agent, name, None) + + async def handler(**kwargs: Any) -> Any: + received.append(kwargs) + done.set() + return await original(**kwargs) if original else None + + setattr(agent, name, handler) + _, connection = connect(use_unstable_protocol=True) + prompt = schema.SystemPrompt(mode="append", content=[schema.TextContentBlock(type="text", text="be brief")]) + # The test agent may answer with an error; only what it received matters here. + with contextlib.suppress(Exception): + await getattr(connection, name)(**params, system_prompt=prompt) + await asyncio.wait_for(done.wait(), 2) + assert received[0]["system_prompt"] == prompt