From afcd2f93d2b0c06ae4e01f9e7ab5dddc2fd81c85 Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Tue, 27 Oct 2026 22:41:11 +0100 Subject: [PATCH] docs(schema): state null handling for every optional v2 field --- agent-client-protocol-schema/src/v2/agent.rs | 96 ++++--- agent-client-protocol-schema/src/v2/client.rs | 22 +- .../src/v2/content.rs | 38 +++ .../src/v2/elicitation.rs | 6 +- agent-client-protocol-schema/src/v2/error.rs | 2 + .../src/v2/tool_call.rs | 12 +- docs/protocol/v2/draft/overview.mdx | 2 + docs/protocol/v2/draft/schema.mdx | 251 ++++++++++++++---- docs/protocol/v2/overview.mdx | 2 + docs/protocol/v2/schema.mdx | 225 +++++++++++++--- schema/v2/schema.json | 112 ++++---- schema/v2/schema.unstable.json | 134 +++++----- 12 files changed, 635 insertions(+), 267 deletions(-) diff --git a/agent-client-protocol-schema/src/v2/agent.rs b/agent-client-protocol-schema/src/v2/agent.rs index 281b13590..422f4318c 100644 --- a/agent-client-protocol-schema/src/v2/agent.rs +++ b/agent-client-protocol-schema/src/v2/agent.rs @@ -197,6 +197,8 @@ pub struct Implementation { /// and easily understood. /// /// If not provided, the name should be used for display. + /// + /// Omitted and `null` are equivalent and mean the `name` is used for display. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] @@ -679,6 +681,8 @@ pub struct AuthMethodAgent { /// Human-readable name of the authentication method. pub name: String, /// Optional description providing more details about this authentication method. + /// + /// Omitted and `null` are equivalent and mean no description is provided. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] @@ -745,6 +749,8 @@ pub struct AuthMethodTerminal { /// Human-readable name of the authentication method. pub name: String, /// Optional description providing more details about this authentication method. + /// + /// Omitted and `null` are equivalent and mean no description is provided. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] @@ -1245,7 +1251,7 @@ pub struct ResumeSessionRequest { pub mcp_servers: Vec, /// Inclusive cursor describing where conversation replay should begin. /// - /// Optional. Omitted or `null` both mean the Agent should resume without + /// Optional. Omitted and `null` are equivalent and mean the Agent should resume without /// replaying previous conversation history. Replay cursors are inclusive: /// replay includes the position identified by the cursor. Supplying /// `{ "type": "start" }` means the Agent should replay all retained @@ -1318,7 +1324,7 @@ impl ResumeSessionRequest { /// Inclusive cursor describing where conversation replay should begin. /// - /// Omitted or `null` both mean the Agent should resume without replaying + /// Omitted and `null` are equivalent and mean the Agent should resume without replaying /// previous conversation history. Replay cursors are inclusive: replay /// includes the position identified by the cursor. Supplying /// `{ "type": "start" }` means the Agent should replay all retained @@ -1728,9 +1734,13 @@ crate::serde_util::default_on_null! { #[non_exhaustive] pub struct ListSessionsRequest { /// Filter sessions by working directory. Must be an absolute path. + /// + /// Omitted and `null` are equivalent and mean sessions are not filtered by working directory. #[serde(default)] pub cwd: Option, /// Opaque cursor token from a previous response's nextCursor field for cursor-based pagination + /// + /// Omitted and `null` are equivalent and mean the first page is requested. #[serde(default)] pub cursor: Option, /// The _meta property is reserved by ACP to allow clients and agents to attach additional @@ -1954,11 +1964,15 @@ pub struct SessionInfo { pub additional_directories: Vec, /// Human-readable title for the session + /// + /// Omitted and `null` are equivalent and mean no title is provided. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] pub title: Option, /// RFC 3339 timestamp of last activity. + /// + /// Omitted and `null` are equivalent and mean the last activity time is not reported. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "format" = "date-time")))] #[serde(default)] @@ -2089,6 +2103,8 @@ pub struct SessionConfigSelectOption { /// Human-readable label for this option value. pub name: String, /// Optional description for this option value. + /// + /// Omitted and `null` are equivalent and mean no description is provided. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] @@ -2395,11 +2411,15 @@ pub struct SessionConfigOption { /// Human-readable label for the option. pub name: String, /// Optional description for the Client to display to the user. + /// + /// Omitted and `null` are equivalent and mean no description is provided. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] pub description: Option, /// Optional semantic category for this option (UX only). + /// + /// Omitted and `null` are equivalent and mean no category is provided. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] @@ -3554,7 +3574,7 @@ impl From for StopReason { pub struct ErrorStopReason { /// The failure, as a JSON-RPC error object. /// - /// Optional. Omitted or `null` both mean the agent is not reporting failure details. + /// Optional. Omitted and `null` are equivalent and mean the agent is not reporting failure details. /// Agents SHOULD include it. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] @@ -3683,16 +3703,22 @@ pub struct Usage { /// Total output tokens. pub output_tokens: u64, /// Total thought/reasoning tokens + /// + /// Omitted and `null` are equivalent and mean the count is not reported. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] pub thought_tokens: Option, /// Total cache read tokens. + /// + /// Omitted and `null` are equivalent and mean the count is not reported. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] pub cached_read_tokens: Option, /// Total cache write tokens. + /// + /// Omitted and `null` are equivalent and mean the count is not reported. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] @@ -4282,7 +4308,7 @@ impl DisableProviderResponse { pub struct AgentCapabilities { /// Session capabilities supported by the agent. /// - /// Optional. Omitted or `null` both mean the agent does not support the + /// Optional. Omitted and `null` are equivalent and mean the agent does not support the /// `session/*` method surface. Supplying `{}` means the agent supports the /// baseline session methods: `session/new`, `session/list`, /// `session/resume`, `session/close`, `session/prompt`, `session/cancel`, @@ -4293,7 +4319,7 @@ pub struct AgentCapabilities { pub session: Option, /// Authentication-related extension capabilities supported by the agent. /// - /// Optional. Omitted or `null` both mean the agent does not advertise any + /// Optional. Omitted and `null` are equivalent and mean the agent does not advertise any /// authentication-related extensions. This field does not advertise support /// for `auth/login` or `auth/logout`; those methods are advertised by a /// non-empty `authMethods` list in the `initialize` response. @@ -4307,7 +4333,7 @@ pub struct AgentCapabilities { /// /// Provider configuration capabilities supported by the agent. /// - /// Optional. Omitted or `null` both mean the agent does not advertise support. + /// Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports provider configuration methods. #[cfg(feature = "unstable_llm_providers")] #[serde_as(deserialize_as = "DefaultOnError")] @@ -4335,7 +4361,7 @@ impl AgentCapabilities { /// Session capabilities supported by the agent. /// - /// Omitted or `null` both mean the agent does not support the `session/*` + /// Omitted and `null` are equivalent and mean the agent does not support the `session/*` /// method surface. Supplying `{}` means the agent supports the baseline /// session methods: `session/new`, `session/list`, `session/resume`, /// `session/close`, `session/prompt`, `session/cancel`, and @@ -4445,7 +4471,7 @@ impl ProvidersCapabilities { pub struct SessionCapabilities { /// Prompt capabilities supported by the agent in `session/prompt` requests. /// - /// Optional. Omitted or `null` both mean the agent does not advertise any + /// Optional. Omitted and `null` are equivalent and mean the agent does not advertise any /// prompt extensions beyond the baseline text and resource-link content /// required by `session/prompt`. #[serde_as(deserialize_as = "DefaultOnError")] @@ -4454,7 +4480,7 @@ pub struct SessionCapabilities { pub prompt: Option, /// MCP capabilities supported by the agent for session lifecycle requests. /// - /// Optional. Omitted or `null` both mean the agent does not advertise MCP + /// Optional. Omitted and `null` are equivalent and mean the agent does not advertise MCP /// server transport support for sessions. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] @@ -4462,7 +4488,7 @@ pub struct SessionCapabilities { pub mcp: Option, /// Whether the agent supports `session/delete`. /// - /// Optional. Omitted or `null` both mean the agent does not advertise support. + /// Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports deleting sessions from `session/list`. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] @@ -4470,7 +4496,7 @@ pub struct SessionCapabilities { pub delete: Option, /// Whether the agent supports `additionalDirectories` on supported session lifecycle requests. /// - /// Optional. Omitted or `null` both mean the agent does not advertise support. + /// Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports `additionalDirectories` on /// supported session lifecycle requests. /// @@ -4486,7 +4512,7 @@ pub struct SessionCapabilities { /// /// Whether the agent supports `systemPrompt` on session lifecycle requests. /// - /// Optional. Omitted or `null` both mean the agent does not advertise support. + /// Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports `systemPrompt` in `append` mode. #[cfg(feature = "unstable_session_system_prompt")] #[serde_as(deserialize_as = "DefaultOnError")] @@ -4499,7 +4525,7 @@ pub struct SessionCapabilities { /// /// Whether the agent supports `session/fork`. /// - /// Optional. Omitted or `null` both mean the agent does not advertise support. + /// Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports forking sessions. #[cfg(feature = "unstable_session_fork")] #[serde_as(deserialize_as = "DefaultOnError")] @@ -4527,7 +4553,7 @@ impl SessionCapabilities { /// Prompt capabilities supported by the agent in `session/prompt` requests. /// - /// Omitted or `null` both mean the agent does not advertise any prompt + /// Omitted and `null` are equivalent and mean the agent does not advertise any prompt /// extensions beyond the baseline text and resource-link content required by /// `session/prompt`. #[must_use] @@ -4538,7 +4564,7 @@ impl SessionCapabilities { /// MCP capabilities supported by the agent for session lifecycle requests. /// - /// Omitted or `null` both mean the agent does not advertise MCP server + /// Omitted and `null` are equivalent and mean the agent does not advertise MCP server /// transport support for sessions. #[must_use] pub fn mcp(mut self, mcp: impl IntoOption) -> Self { @@ -4548,7 +4574,7 @@ impl SessionCapabilities { /// Whether the agent supports `session/delete`. /// - /// Omitted or `null` both mean the agent does not advertise support. + /// Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports deleting sessions from `session/list`. #[must_use] pub fn delete(mut self, delete: impl IntoOption) -> Self { @@ -4558,7 +4584,7 @@ impl SessionCapabilities { /// Whether the agent supports `additionalDirectories` on supported session lifecycle requests. /// - /// Omitted or `null` both mean the agent does not advertise support. + /// Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports `additionalDirectories` on /// supported session lifecycle requests. /// @@ -4579,7 +4605,7 @@ impl SessionCapabilities { /// /// Whether the agent supports `systemPrompt` on session lifecycle requests. /// - /// Omitted or `null` both mean the agent does not advertise support. + /// Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports `systemPrompt` in `append` mode. #[cfg(feature = "unstable_session_system_prompt")] #[must_use] @@ -4594,7 +4620,7 @@ impl SessionCapabilities { #[cfg(feature = "unstable_session_fork")] /// Whether the agent supports `session/fork`. /// - /// Omitted or `null` both mean the agent does not advertise support. + /// Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports forking sessions. #[must_use] pub fn fork(mut self, fork: impl IntoOption) -> Self { @@ -4715,7 +4741,7 @@ impl SessionAdditionalDirectoriesCapabilities { pub struct SessionSystemPromptCapabilities { /// Delivery modes the agent supports in addition to `append`. /// - /// Optional. Omitted or `null` both mean the agent supports only `append`. + /// Optional. Omitted and `null` are equivalent and mean the agent supports only `append`. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] @@ -4742,7 +4768,7 @@ impl SessionSystemPromptCapabilities { /// Delivery modes the agent supports in addition to `append`. /// - /// Omitted or `null` both mean the agent supports only `append`. + /// Omitted and `null` are equivalent and mean the agent supports only `append`. #[must_use] pub fn mode(mut self, mode: impl IntoOption) -> Self { self.mode = mode.into_option(); @@ -4779,7 +4805,7 @@ impl SessionSystemPromptCapabilities { pub struct SessionSystemPromptModeCapabilities { /// Whether the agent supports `override` mode. /// - /// Optional. Omitted or `null` both mean the agent does not advertise support. + /// Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports replacing its built-in default /// instructions with the client-provided system prompt. #[serde_as(deserialize_as = "DefaultOnError")] @@ -4808,7 +4834,7 @@ impl SessionSystemPromptModeCapabilities { /// Whether the agent supports `override` mode. /// - /// Omitted or `null` both mean the agent does not advertise support. + /// Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports replacing its built-in default /// instructions with the client-provided system prompt. #[must_use] @@ -4946,7 +4972,7 @@ impl SessionForkCapabilities { pub struct PromptCapabilities { /// Agent supports `image` content blocks. /// - /// Optional. Omitted or `null` both mean the agent does not advertise support. + /// Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports image content in prompts. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] @@ -4954,7 +4980,7 @@ pub struct PromptCapabilities { pub image: Option, /// Agent supports `audio` content blocks. /// - /// Optional. Omitted or `null` both mean the agent does not advertise support. + /// Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports audio content in prompts. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] @@ -4965,7 +4991,7 @@ pub struct PromptCapabilities { /// When enabled, the Client is allowed to include `resource` content blocks /// in prompt requests for pieces of context that are referenced in the message. /// - /// Optional. Omitted or `null` both mean the agent does not advertise support. + /// Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports embedded context in prompts. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] @@ -4992,7 +5018,7 @@ impl PromptCapabilities { /// Agent supports `image` content blocks. /// - /// Omitted or `null` both mean the agent does not advertise support. + /// Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports image content in prompts. #[must_use] pub fn image(mut self, image: impl IntoOption) -> Self { @@ -5002,7 +5028,7 @@ impl PromptCapabilities { /// Agent supports `audio` content blocks. /// - /// Omitted or `null` both mean the agent does not advertise support. + /// Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports audio content in prompts. #[must_use] pub fn audio(mut self, audio: impl IntoOption) -> Self { @@ -5015,7 +5041,7 @@ impl PromptCapabilities { /// When enabled, the Client is allowed to include `resource` content blocks /// in prompt requests for pieces of context that are referenced in the message. /// - /// Omitted or `null` both mean the agent does not advertise support. + /// Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports embedded context in prompts. #[must_use] pub fn embedded_context( @@ -5168,7 +5194,7 @@ impl PromptEmbeddedContextCapabilities { pub struct McpCapabilities { /// Agent supports `stdio` MCP servers. /// - /// Optional. Omitted or `null` both mean the agent does not advertise support. + /// Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports stdio MCP server transports. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] @@ -5176,7 +5202,7 @@ pub struct McpCapabilities { pub stdio: Option, /// Agent supports `http` MCP servers. /// - /// Optional. Omitted or `null` both mean the agent does not advertise support. + /// Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports HTTP MCP server transports. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] @@ -5188,7 +5214,7 @@ pub struct McpCapabilities { /// /// Agent supports `acp` MCP servers. /// - /// Optional. Omitted or `null` both mean the agent does not advertise support. + /// Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports ACP MCP server transports. #[cfg(feature = "unstable_mcp_over_acp")] #[serde_as(deserialize_as = "DefaultOnError")] @@ -5216,7 +5242,7 @@ impl McpCapabilities { /// Agent supports `stdio` MCP servers. /// - /// Omitted or `null` both mean the agent does not advertise support. + /// Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports stdio MCP server transports. #[must_use] pub fn stdio(mut self, stdio: impl IntoOption) -> Self { @@ -5226,7 +5252,7 @@ impl McpCapabilities { /// Agent supports `http` MCP servers. /// - /// Omitted or `null` both mean the agent does not advertise support. + /// Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports HTTP MCP server transports. #[must_use] pub fn http(mut self, http: impl IntoOption) -> Self { @@ -5241,7 +5267,7 @@ impl McpCapabilities { /// Agent supports `acp` MCP servers. #[cfg(feature = "unstable_mcp_over_acp")] /// - /// Omitted or `null` both mean the agent does not advertise support. + /// Omitted and `null` are equivalent and mean the agent does not advertise support. /// Supplying `{}` means the agent supports ACP MCP server transports. #[must_use] pub fn acp(mut self, acp: impl IntoOption) -> Self { diff --git a/agent-client-protocol-schema/src/v2/client.rs b/agent-client-protocol-schema/src/v2/client.rs index bd83dc7cd..9358fac17 100644 --- a/agent-client-protocol-schema/src/v2/client.rs +++ b/agent-client-protocol-schema/src/v2/client.rs @@ -1096,7 +1096,7 @@ impl SubagentUpdate { #[non_exhaustive] pub struct SubagentSessionCapabilities { /// Permits the client to cancel this child's current work without ending - /// the session. Omitted or `null` means unsupported; an object (including + /// the session. Omitted and `null` are equivalent and mean unsupported; an object (including /// `{}`) means supported. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] @@ -1463,6 +1463,8 @@ pub struct UsageUpdate { /// Total context window size in tokens. pub size: u64, /// Cumulative session cost (optional). + /// + /// Omitted and `null` are equivalent and mean no cost is reported. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] @@ -1648,7 +1650,7 @@ pub struct IdleStateUpdate { /// /// Token usage for completed foreground work. /// - /// Optional. Omitted or `null` both mean the agent is not reporting token + /// Optional. Omitted and `null` are equivalent and mean the agent is not reporting token /// usage for this state update. #[cfg(feature = "unstable_end_turn_token_usage")] #[serde_as(deserialize_as = "DefaultOnError")] @@ -1722,7 +1724,7 @@ fn idle_state_update_schema(schema: &mut Schema) { properties.insert( "stopReason".into(), serde_json::json!({ - "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: [Stop Reasons](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#stop-reasons)", + "description": "Why foreground work stopped. The value selects one of this type's variants, which may add fields of their own.\n\nOptional. Omitted and `null` are equivalent and mean the agent is not reporting a stop reason; a malformed value is treated the same way.\n\nSee protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#stop-reasons)", "type": ["string", "null"], "x-deserialize-default-on-error": true }), @@ -2475,6 +2477,8 @@ pub struct Command { /// Human-readable description of what the command does. pub description: String, /// Input for the command if required + /// + /// Omitted and `null` are equivalent and mean the command takes no input. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] @@ -2684,7 +2688,7 @@ pub struct RequestPermissionRequest { /// Optional human-readable explanation of why permission is needed. /// /// This text is specific to the permission prompt and does not update any - /// subject's displayed content. Omitted or `null` both mean no separate + /// subject's displayed content. Omitted and `null` are equivalent and mean no separate /// permission description was provided. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] @@ -2692,7 +2696,7 @@ pub struct RequestPermissionRequest { pub description: Option, /// Optional structured context about the operation requiring permission. /// - /// Omitted or `null` both mean no structured subject was provided. + /// Omitted and `null` are equivalent and mean no structured subject was provided. #[serde(default)] pub subject: Option, /// Available permission options for the user to choose from. @@ -3337,7 +3341,7 @@ pub struct ClientCapabilities { /// Determines which authentication method types the agent may include /// in its `InitializeResponse`. /// - /// Optional. Omitted or `null` both mean the client does not advertise any + /// Optional. Omitted and `null` are equivalent and mean the client does not advertise any /// authentication-method extensions. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] @@ -3346,7 +3350,7 @@ pub struct ClientCapabilities { /// Elicitation capabilities supported by the client. /// Determines which elicitation modes the agent may use. /// - /// Optional. Omitted or `null` both mean the client does not advertise + /// Optional. Omitted and `null` are equivalent and mean the client does not advertise /// elicitation support. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] @@ -3415,7 +3419,7 @@ impl ClientCapabilities { pub struct ClientAuthCapabilities { /// Whether the client supports `terminal` authentication methods. /// - /// Optional. Omitted or `null` both mean the client does not advertise support. + /// Optional. Omitted and `null` are equivalent and mean the client does not advertise support. /// The client should supply `{}` only when it can reproduce the configured /// agent invocation in an interactive terminal. Supplying `{}` means the /// agent may include `terminal` entries in its authentication methods. @@ -3444,7 +3448,7 @@ impl ClientAuthCapabilities { /// Whether the client supports `terminal` authentication methods. /// - /// Omitted or `null` both mean the client does not advertise support. + /// Omitted and `null` are equivalent and mean the client does not advertise support. /// The client should supply `{}` only when it can reproduce the configured /// agent invocation in an interactive terminal. Supplying `{}` means the /// agent may include `AuthMethod::Terminal` entries in its authentication diff --git a/agent-client-protocol-schema/src/v2/content.rs b/agent-client-protocol-schema/src/v2/content.rs index c97edc86b..86a0aa6c2 100644 --- a/agent-client-protocol-schema/src/v2/content.rs +++ b/agent-client-protocol-schema/src/v2/content.rs @@ -206,6 +206,8 @@ pub struct TextContent { /// Text payload carried by this content block. pub text: String, /// Optional annotations that help clients decide how to display or route this content. + /// + /// Omitted and `null` are equivalent and mean no annotations are provided. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] @@ -272,12 +274,16 @@ pub struct ImageContent { /// MIME type describing the encoded media payload. pub mime_type: MediaType, /// URI associated with this resource or media payload. + /// + /// Omitted and `null` are equivalent and mean no URI is associated with the image. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[cfg_attr(feature = "schemars", schemars(url))] #[serde(default)] pub uri: Option, /// Optional annotations that help clients decide how to display or route this content. + /// + /// Omitted and `null` are equivalent and mean no annotations are provided. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] @@ -347,6 +353,8 @@ pub struct AudioContent { /// MIME type describing the encoded media payload. pub mime_type: MediaType, /// Optional annotations that help clients decide how to display or route this content. + /// + /// Omitted and `null` are equivalent and mean no annotations are provided. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] @@ -404,6 +412,8 @@ pub struct EmbeddedResource { /// Embedded resource payload, either text or binary data. pub resource: EmbeddedResourceResource, /// Optional annotations that help clients decide how to display or route this content. + /// + /// Omitted and `null` are equivalent and mean no annotations are provided. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] @@ -476,6 +486,8 @@ pub struct TextResourceContents { #[cfg_attr(feature = "schemars", schemars(url))] pub uri: String, /// MIME type describing the encoded media payload. + /// + /// Omitted and `null` are equivalent and mean the MIME type is not specified. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] @@ -538,6 +550,8 @@ pub struct BlobResourceContents { #[cfg_attr(feature = "schemars", schemars(url))] pub uri: String, /// MIME type describing the encoded media payload. + /// + /// Omitted and `null` are equivalent and mean the MIME type is not specified. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] @@ -599,31 +613,43 @@ pub struct ResourceLink { #[cfg_attr(feature = "schemars", schemars(url))] pub uri: String, /// Optional display title for end-user UI. + /// + /// Omitted and `null` are equivalent and mean no title is provided. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] pub title: Option, /// Optional human-readable details shown with this protocol object. + /// + /// Omitted and `null` are equivalent and mean no description is provided. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] pub description: Option, /// Optional set of sized icons that the client can display in a user interface. + /// + /// Omitted and `null` are equivalent and mean no icons are provided. #[serde_as(deserialize_as = "DefaultOnError>>")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))] #[serde(default)] pub icons: Option>, /// MIME type describing the encoded media payload. + /// + /// Omitted and `null` are equivalent and mean the MIME type is not specified. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] pub mime_type: Option, /// Optional size of the linked resource in bytes, if known. + /// + /// Omitted and `null` are equivalent and mean the size is not known. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] pub size: Option, /// Optional annotations that help clients decide how to display or route this content. + /// + /// Omitted and `null` are equivalent and mean no annotations are provided. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] @@ -723,6 +749,8 @@ pub struct Icon { #[cfg_attr(feature = "schemars", schemars(url))] pub src: String, /// Optional MIME type override if the source MIME type is missing or generic. + /// + /// Omitted and `null` are equivalent and mean the source MIME type is used. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] @@ -732,11 +760,15 @@ pub struct Icon { /// `"any"` for scalable formats like SVG. /// /// If not provided, the client should assume that the icon can be used at any size. + /// + /// Omitted and `null` are equivalent and mean no sizes are specified. #[serde_as(deserialize_as = "DefaultOnError>>")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))] #[serde(default)] pub sizes: Option>, /// Optional theme this icon is designed for. + /// + /// Omitted and `null` are equivalent and mean the icon is not theme-specific. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] @@ -827,6 +859,8 @@ pub enum IconTheme { #[non_exhaustive] pub struct Annotations { /// Intended recipients for this content, such as the user or assistant. + /// + /// Omitted and `null` are equivalent and mean no audience is specified. #[serde_as(deserialize_as = "DefaultOnError>>")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))] #[serde(default)] @@ -834,11 +868,15 @@ pub struct Annotations { /// Timestamp indicating when the underlying resource was last modified. /// /// Must be an RFC 3339 formatted string (e.g., "2025-01-12T15:00:58Z"). + /// + /// Omitted and `null` are equivalent and mean the modification time is not reported. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "format" = "date-time")))] #[serde(default)] pub last_modified: Option, /// Relative importance of this content when clients choose what to surface. + /// + /// Omitted and `null` are equivalent and mean no priority is specified. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[cfg_attr(feature = "schemars", schemars(range(min = 0, max = 1)))] diff --git a/agent-client-protocol-schema/src/v2/elicitation.rs b/agent-client-protocol-schema/src/v2/elicitation.rs index 84b74ff15..85b3dc3c6 100644 --- a/agent-client-protocol-schema/src/v2/elicitation.rs +++ b/agent-client-protocol-schema/src/v2/elicitation.rs @@ -1282,7 +1282,7 @@ pub struct ElicitationCapabilities { pub form: Option, /// Whether the client supports URL-based elicitation. /// - /// Optional. Omitted or `null` both mean the client does not advertise support. + /// Optional. Omitted and `null` are equivalent and mean the client does not advertise support. /// Supplying `{}` means the client supports URL-based elicitation. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] @@ -1335,7 +1335,7 @@ impl ElicitationCapabilities { /// Whether the client supports URL-based elicitation. /// - /// Omitted or `null` both mean the client does not advertise support. + /// Omitted and `null` are equivalent and mean the client does not advertise support. /// Supplying `{}` means the client supports URL-based elicitation. #[must_use] pub fn url(mut self, url: impl IntoOption) -> Self { @@ -2013,6 +2013,8 @@ impl From for ElicitationAction { #[non_exhaustive] pub struct ElicitationAcceptAction { /// The user-provided content, if any, as an object matching the requested schema. + /// + /// Omitted and `null` are equivalent and mean no content is provided. #[serde(default)] pub content: Option>, } diff --git a/agent-client-protocol-schema/src/v2/error.rs b/agent-client-protocol-schema/src/v2/error.rs index ffadc6f83..1af803f99 100644 --- a/agent-client-protocol-schema/src/v2/error.rs +++ b/agent-client-protocol-schema/src/v2/error.rs @@ -42,6 +42,8 @@ pub struct Error { pub message: String, /// Optional primitive or structured value that contains additional information about the error. /// This may include debugging information or context-specific details. + /// + /// Omitted and `null` are equivalent and mean no additional data is provided. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] diff --git a/agent-client-protocol-schema/src/v2/tool_call.rs b/agent-client-protocol-schema/src/v2/tool_call.rs index 39301cdc3..fb1db9440 100644 --- a/agent-client-protocol-schema/src/v2/tool_call.rs +++ b/agent-client-protocol-schema/src/v2/tool_call.rs @@ -565,8 +565,8 @@ pub struct Diff { pub changes: Vec, /// Renderable patch text for some or all of the structured changes. /// - /// Agents SHOULD provide patch text whenever feasible. Omitted or `null` - /// means no renderable patch text was provided. + /// Agents SHOULD provide patch text whenever feasible. Omitted and `null` are + /// equivalent and mean no renderable patch text was provided. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] @@ -728,14 +728,14 @@ pub enum DiffFileType { pub struct DiffChange { /// File content kind after the operation (for `delete`, of the deleted file). /// - /// Omitted or `null` means the content kind is unknown. + /// Omitted and `null` are equivalent and mean the content kind is unknown. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] pub file_type: Option, /// MIME type of the file contents after the operation (for `delete`, of the deleted file). /// - /// Omitted or `null` means the MIME type is unknown. + /// Omitted and `null` are equivalent and mean the MIME type is unknown. #[serde_as(deserialize_as = "DefaultOnError")] #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] @@ -803,7 +803,7 @@ impl DiffChange { /// File content kind. /// - /// Omitted or `null` means the content kind is unknown. + /// Omitted and `null` are equivalent and mean the content kind is unknown. #[must_use] pub fn file_type(mut self, file_type: impl IntoOption) -> Self { self.file_type = file_type.into_option(); @@ -812,7 +812,7 @@ impl DiffChange { /// MIME type of the file contents. /// - /// Omitted or `null` means the MIME type is unknown. + /// Omitted and `null` are equivalent and mean the MIME type is unknown. #[must_use] pub fn mime_type(mut self, mime_type: impl IntoOption) -> Self { self.mime_type = mime_type.into_option(); diff --git a/docs/protocol/v2/draft/overview.mdx b/docs/protocol/v2/draft/overview.mdx index 77f793ea1..2758c5aba 100644 --- a/docs/protocol/v2/draft/overview.mdx +++ b/docs/protocol/v2/draft/overview.mdx @@ -231,6 +231,8 @@ See [Errors](/protocol/v2/draft/error) for the error codes ACP uses and when to Unless explicitly defined otherwise in the schema, ACP-defined JSON object property keys use `camelCase`. String values carried by discriminator fields use `snake_case`. The JSON-RPC envelope fields (`jsonrpc`, `id`, `method`, `params`, `result`, and `error`) follow the JSON-RPC 2.0 specification. +An optional field that is omitted and the same field set to `null` are equivalent, unless the field says otherwise. Upsert updates are the exception: there an omitted field leaves the stored value unchanged and `null` clears it. + Selected enum-like fields and tagged unions can define custom or future fallbacks. For those fields, `_`-prefixed values are reserved for implementation-specific extensions, while unknown non-underscore values are reserved for future ACP variants. ## Extensibility diff --git a/docs/protocol/v2/draft/schema.mdx b/docs/protocol/v2/draft/schema.mdx index ba43c9a3d..bbfd24b0c 100644 --- a/docs/protocol/v2/draft/schema.mdx +++ b/docs/protocol/v2/draft/schema.mdx @@ -736,9 +736,15 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d SessionListCursor | null} > Opaque cursor token from a previous response's nextCursor field for cursor-based pagination + +Omitted and `null` are equivalent and mean the first page is requested. + AbsolutePath | null} > Filter sessions by working directory. Must be an absolute path. + +Omitted and `null` are equivalent and mean sessions are not filtered by working directory. + #### ListSessionsResponse @@ -1014,7 +1020,7 @@ the request `cwd` matches the session's `cwd`. ReplayFrom | null} > Inclusive cursor describing where conversation replay should begin. -Optional. Omitted or `null` both mean the Agent should resume without +Optional. Omitted and `null` are equivalent and mean the Agent should resume without replaying previous conversation history. Replay cursors are inclusive: replay includes the position identified by the cursor. Supplying `\{ "type": "start" \}` means the Agent should replay all retained @@ -1485,8 +1491,11 @@ The user accepted and provided content. The discriminator value. Must be `"accept"`. - + The user-provided content, if any, as an object matching the requested schema. + +Omitted and `null` are equivalent and mean no content is provided. + @@ -1677,7 +1686,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Optional human-readable explanation of why permission is needed. This text is specific to the permission prompt and does not update any -subject's displayed content. Omitted or `null` both mean no separate +subject's displayed content. Omitted and `null` are equivalent and mean no separate permission description was provided. @@ -1691,7 +1700,7 @@ Must contain at least one option. RequestPermissionSubject | null} > Optional structured context about the operation requiring permission. -Omitted or `null` both mean no structured subject was provided. +Omitted and `null` are equivalent and mean no structured subject was provided. @@ -1867,7 +1876,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d AgentAuthCapabilities | null} > Authentication-related extension capabilities supported by the agent. -Optional. Omitted or `null` both mean the agent does not advertise any +Optional. Omitted and `null` are equivalent and mean the agent does not advertise any authentication-related extensions. This field does not advertise support for `auth/login` or `auth/logout`; those methods are advertised by a non-empty `authMethods` list in the `initialize` response. @@ -1880,14 +1889,14 @@ This capability is not part of the spec yet, and may be removed or changed at an Provider configuration capabilities supported by the agent. -Optional. Omitted or `null` both mean the agent does not advertise support. +Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports provider configuration methods. SessionCapabilities | null} > Session capabilities supported by the agent. -Optional. Omitted or `null` both mean the agent does not support the +Optional. Omitted and `null` are equivalent and mean the agent does not support the `session/*` method surface. Supplying `\{\}` means the agent supports the baseline session methods: `session/new`, `session/list`, `session/resume`, `session/close`, `session/prompt`, `session/cancel`, @@ -1989,18 +1998,25 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Role[] | null} > Intended recipients for this content, such as the user or assistant. + +Omitted and `null` are equivalent and mean no audience is specified. + Timestamp indicating when the underlying resource was last modified. Must be an RFC 3339 formatted string (e.g., "2025-01-12T15:00:58Z"). +Omitted and `null` are equivalent and mean the modification time is not reported. + - Format: `date-time` Relative importance of this content when clients choose what to surface. +Omitted and `null` are equivalent and mean no priority is specified. + | Constraint | Value | | ---------- | ----- | | Minimum | `0` | @@ -2026,6 +2042,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Annotations | null} > Optional annotations that help clients decide how to display or route this content. + +Omitted and `null` are equivalent and mean no annotations are provided. + Base64-encoded media payload. @@ -2064,6 +2083,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Optional description providing more details about this authentication method. + +Omitted and `null` are equivalent and mean no description is provided. + EnvVariable[]} > Additional environment variables to set on the configured agent invocation for terminal auth. @@ -2100,6 +2122,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Optional description providing more details about this authentication method. + +Omitted and `null` are equivalent and mean no description is provided. + AuthMethodId} required> Unique identifier for this authentication method. @@ -2165,6 +2190,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Optional description providing more details about this authentication method. + +Omitted and `null` are equivalent and mean no description is provided. + AuthMethodId} required> Unique identifier for this authentication method. @@ -2206,6 +2234,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Optional description providing more details about this authentication method. + +Omitted and `null` are equivalent and mean no description is provided. + EnvVariable[]} > Additional environment variables to set on the configured agent invocation for terminal auth. @@ -2245,6 +2276,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d AvailableCommandInput | null} > Input for the command if required + +Omitted and `null` are equivalent and mean the command takes no input. + Command name (e.g., `create_plan`, `research_codebase`). @@ -2387,6 +2421,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d MediaType | null} > MIME type describing the encoded media payload. + +Omitted and `null` are equivalent and mean the MIME type is not specified. + URI associated with this resource or media payload. @@ -2470,7 +2507,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d TerminalAuthCapabilities | null} > Whether the client supports `terminal` authentication methods. -Optional. Omitted or `null` both mean the client does not advertise support. +Optional. Omitted and `null` are equivalent and mean the client does not advertise support. The client should supply `\{\}` only when it can reproduce the configured agent invocation in an interactive terminal. Supplying `\{\}` means the agent may include `terminal` entries in its authentication methods. @@ -2503,7 +2540,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Determines which authentication method types the agent may include in its `InitializeResponse`. -Optional. Omitted or `null` both mean the client does not advertise any +Optional. Omitted and `null` are equivalent and mean the client does not advertise any authentication-method extensions. @@ -2511,7 +2548,7 @@ authentication-method extensions. Elicitation capabilities supported by the client. Determines which elicitation modes the agent may use. -Optional. Omitted or `null` both mean the client does not advertise +Optional. Omitted and `null` are equivalent and mean the client does not advertise elicitation support. @@ -2539,6 +2576,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d AvailableCommandInput | null} > Input for the command if required + +Omitted and `null` are equivalent and mean the command takes no input. + Command name (e.g., `create_plan`, `research_codebase`). @@ -2752,6 +2792,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Annotations | null} > Optional annotations that help clients decide how to display or route this content. + +Omitted and `null` are equivalent and mean no annotations are provided. + Text payload carried by this content block. @@ -2780,6 +2823,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Annotations | null} > Optional annotations that help clients decide how to display or route this content. + +Omitted and `null` are equivalent and mean no annotations are provided. + Base64-encoded media payload. @@ -2796,6 +2842,8 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d URI associated with this resource or media payload. +Omitted and `null` are equivalent and mean no URI is associated with the image. + - Format: `uri` @@ -2820,6 +2868,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Annotations | null} > Optional annotations that help clients decide how to display or route this content. + +Omitted and `null` are equivalent and mean no annotations are provided. + Base64-encoded media payload. @@ -2854,15 +2905,27 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Annotations | null} > Optional annotations that help clients decide how to display or route this content. + +Omitted and `null` are equivalent and mean no annotations are provided. + Optional human-readable details shown with this protocol object. + +Omitted and `null` are equivalent and mean no description is provided. + Icon[] | null} > Optional set of sized icons that the client can display in a user interface. + +Omitted and `null` are equivalent and mean no icons are provided. + MediaType | null} > MIME type describing the encoded media payload. + +Omitted and `null` are equivalent and mean the MIME type is not specified. + Human-readable name shown for this protocol object. @@ -2870,11 +2933,16 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Optional size of the linked resource in bytes, if known. +Omitted and `null` are equivalent and mean the size is not known. + - Minimum: `0` Optional display title for end-user UI. + +Omitted and `null` are equivalent and mean no title is provided. + The discriminator value. Must be `"resource_link"`. @@ -2908,6 +2976,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Annotations | null} > Optional annotations that help clients decide how to display or route this content. + +Omitted and `null` are equivalent and mean no annotations are provided. + EmbeddedResourceResource} required> Embedded resource payload, either text or binary data. @@ -3032,8 +3103,8 @@ Clients can use this field without parsing patch text to determine affected path DiffPatch | null} > Renderable patch text for some or all of the structured changes. -Agents SHOULD provide patch text whenever feasible. Omitted or `null` -means no renderable patch text was provided. +Agents SHOULD provide patch text whenever feasible. Omitted and `null` are +equivalent and mean no renderable patch text was provided. @@ -3059,13 +3130,13 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d DiffFileType | null} > File content kind after the operation (for `delete`, of the deleted file). -Omitted or `null` means the content kind is unknown. +Omitted and `null` are equivalent and mean the content kind is unknown. MediaType | null} > MIME type of the file contents after the operation (for `delete`, of the deleted file). -Omitted or `null` means the MIME type is unknown. +Omitted and `null` are equivalent and mean the MIME type is unknown. @@ -3331,8 +3402,11 @@ The user accepted the elicitation and provided content. **Properties:** - + The user-provided content, if any, as an object matching the requested schema. + +Omitted and `null` are equivalent and mean no content is provided. + ## ElicitationCapabilities @@ -3361,7 +3435,7 @@ Supplying `\{\}` explicitly advertises form support. ElicitationUrlCapabilities | null} > Whether the client supports URL-based elicitation. -Optional. Omitted or `null` both mean the client does not advertise support. +Optional. Omitted and `null` are equivalent and mean the client does not advertise support. Supplying `\{\}` means the client supports URL-based elicitation. @@ -3975,6 +4049,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Annotations | null} > Optional annotations that help clients decide how to display or route this content. + +Omitted and `null` are equivalent and mean no annotations are provided. + EmbeddedResourceResource} required> Embedded resource payload, either text or binary data. @@ -4001,6 +4078,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d MediaType | null} > MIME type describing the encoded media payload. + +Omitted and `null` are equivalent and mean the MIME type is not specified. + Text payload carried by this content block. @@ -4036,6 +4116,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d MediaType | null} > MIME type describing the encoded media payload. + +Omitted and `null` are equivalent and mean the MIME type is not specified. + URI associated with this resource or media payload. @@ -4113,17 +4196,19 @@ See protocol docs: [JSON-RPC Error Object](https://www.jsonrpc.org/specification **Properties:** ErrorCode} required> - A number indicating the error type that occurred. This must be an integer as - defined in the JSON-RPC specification. + A number indicating the error type that occurred. +This must be an integer as defined in the JSON-RPC specification. - - Optional primitive or structured value that contains additional information - about the error. This may include debugging information or context-specific - details. + + Optional primitive or structured value that contains additional information about the error. +This may include debugging information or context-specific details. + +Omitted and `null` are equivalent and mean no additional data is provided. + - A string providing a short description of the error. The message should be - limited to a concise single sentence. + A string providing a short description of the error. +The message should be limited to a concise single sentence. ## ErrorCode @@ -4193,7 +4278,7 @@ Details of a failure that ended active work. Error | null} > The failure, as a JSON-RPC error object. -Optional. Omitted or `null` both mean the agent is not reporting failure details. +Optional. Omitted and `null` are equivalent and mean the agent is not reporting failure details. Agents SHOULD include it. @@ -4263,6 +4348,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d MediaType | null} > Optional MIME type override if the source MIME type is missing or generic. + +Omitted and `null` are equivalent and mean the source MIME type is used. + <>"string"[] | null} > Optional array of strings that specify sizes at which the icon can be used. @@ -4271,6 +4359,8 @@ Each string should be in `WxH` format (e.g., `"48x48"`, `"96x96"`) or If not provided, the client should assume that the icon can be used at any size. +Omitted and `null` are equivalent and mean no sizes are specified. + A standard URI pointing to an icon resource. @@ -4280,6 +4370,9 @@ If not provided, the client should assume that the icon can be used at any size. IconTheme | null} > Optional theme this icon is designed for. + +Omitted and `null` are equivalent and mean the icon is not theme-specific. + ## IconTheme @@ -4331,7 +4424,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d 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. +Optional. Omitted and `null` are equivalent and mean the agent is not reporting a stop reason; a malformed value is treated the same way. See protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/v2/draft/prompt-lifecycle#stop-reasons) @@ -4343,7 +4436,7 @@ This capability is not part of the spec yet, and may be removed or changed at an Token usage for completed foreground work. -Optional. Omitted or `null` both mean the agent is not reporting token +Optional. Omitted and `null` are equivalent and mean the agent is not reporting token usage for this state update. @@ -4433,7 +4526,7 @@ insertion, the prompt's response remains successful. Error | null} > The failure, as a JSON-RPC error object. -Optional. Omitted or `null` both mean the agent is not reporting failure details. +Optional. Omitted and `null` are equivalent and mean the agent is not reporting failure details. Agents SHOULD include it. @@ -4493,6 +4586,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Annotations | null} > Optional annotations that help clients decide how to display or route this content. + +Omitted and `null` are equivalent and mean no annotations are provided. + Base64-encoded media payload. @@ -4506,6 +4602,8 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d URI associated with this resource or media payload. +Omitted and `null` are equivalent and mean no URI is associated with the image. + - Format: `uri` @@ -4538,6 +4636,8 @@ and easily understood. If not provided, the name should be used for display. +Omitted and `null` are equivalent and mean the `name` is used for display. + Version of the implementation. Can be displayed to the user or used @@ -4681,21 +4781,21 @@ This capability is not part of the spec yet, and may be removed or changed at an Agent supports `acp` MCP servers. -Optional. Omitted or `null` both mean the agent does not advertise support. +Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports ACP MCP server transports. McpHttpCapabilities | null} > Agent supports `http` MCP servers. -Optional. Omitted or `null` both mean the agent does not advertise support. +Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports HTTP MCP server transports. McpStdioCapabilities | null} > Agent supports `stdio` MCP servers. -Optional. Omitted or `null` both mean the agent does not advertise support. +Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports stdio MCP server transports. @@ -5738,7 +5838,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d PromptAudioCapabilities | null} > Agent supports `audio` content blocks. -Optional. Omitted or `null` both mean the agent does not advertise support. +Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports audio content in prompts. @@ -5748,14 +5848,14 @@ Supplying `\{\}` means the agent supports audio content in prompts. When enabled, the Client is allowed to include `resource` content blocks in prompt requests for pieces of context that are referenced in the message. -Optional. Omitted or `null` both mean the agent does not advertise support. +Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports embedded context in prompts. PromptImageCapabilities | null} > Agent supports `image` content blocks. -Optional. Omitted or `null` both mean the agent does not advertise support. +Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports image content in prompts. @@ -6214,15 +6314,27 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Annotations | null} > Optional annotations that help clients decide how to display or route this content. + +Omitted and `null` are equivalent and mean no annotations are provided. + Optional human-readable details shown with this protocol object. + +Omitted and `null` are equivalent and mean no description is provided. + Icon[] | null} > Optional set of sized icons that the client can display in a user interface. + +Omitted and `null` are equivalent and mean no icons are provided. + MediaType | null} > MIME type describing the encoded media payload. + +Omitted and `null` are equivalent and mean the MIME type is not specified. + Human-readable name shown for this protocol object. @@ -6230,11 +6342,16 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Optional size of the linked resource in bytes, if known. +Omitted and `null` are equivalent and mean the size is not known. + - Minimum: `0` Optional display title for end-user UI. + +Omitted and `null` are equivalent and mean no title is provided. + URI associated with this resource or media payload. @@ -6377,7 +6494,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d SessionAdditionalDirectoriesCapabilities | null} > Whether the agent supports `additionalDirectories` on supported session lifecycle requests. -Optional. Omitted or `null` both mean the agent does not advertise support. +Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports `additionalDirectories` on supported session lifecycle requests. @@ -6388,7 +6505,7 @@ complete ordered additional-root list associated with a listed session. SessionDeleteCapabilities | null} > Whether the agent supports `session/delete`. -Optional. Omitted or `null` both mean the agent does not advertise support. +Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports deleting sessions from `session/list`. @@ -6399,21 +6516,21 @@ This capability is not part of the spec yet, and may be removed or changed at an Whether the agent supports `session/fork`. -Optional. Omitted or `null` both mean the agent does not advertise support. +Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports forking sessions. McpCapabilities | null} > MCP capabilities supported by the agent for session lifecycle requests. -Optional. Omitted or `null` both mean the agent does not advertise MCP +Optional. Omitted and `null` are equivalent and mean the agent does not advertise MCP server transport support for sessions. PromptCapabilities | null} > Prompt capabilities supported by the agent in `session/prompt` requests. -Optional. Omitted or `null` both mean the agent does not advertise any +Optional. Omitted and `null` are equivalent and mean the agent does not advertise any prompt extensions beyond the baseline text and resource-link content required by `session/prompt`. @@ -6425,7 +6542,7 @@ This capability is not part of the spec yet, and may be removed or changed at an Whether the agent supports `systemPrompt` on session lifecycle requests. -Optional. Omitted or `null` both mean the agent does not advertise support. +Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports `systemPrompt` in `append` mode. @@ -6472,12 +6589,18 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d SessionConfigOptionCategory | null} > Optional semantic category for this option (UX only). + +Omitted and `null` are equivalent and mean no category is provided. + SessionConfigId} required> Unique identifier for the configuration option. Optional description for the Client to display to the user. + +Omitted and `null` are equivalent and mean no description is provided. + Human-readable label for the option. @@ -6659,6 +6782,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Optional description for this option value. + +Omitted and `null` are equivalent and mean no description is provided. + Human-readable label for this option value. @@ -6772,10 +6898,15 @@ reports no additional roots. Human-readable title for the session + +Omitted and `null` are equivalent and mean no title is provided. + RFC 3339 timestamp of last activity. +Omitted and `null` are equivalent and mean the last activity time is not reported. + - Format: `date-time` @@ -6938,7 +7069,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d SessionSystemPromptModeCapabilities | null} > Delivery modes the agent supports in addition to `append`. -Optional. Omitted or `null` both mean the agent supports only `append`. +Optional. Omitted and `null` are equivalent and mean the agent supports only `append`. @@ -6968,7 +7099,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d SessionSystemPromptOverrideCapabilities | null} > Whether the agent supports `override` mode. -Optional. Omitted or `null` both mean the agent does not advertise support. +Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports replacing its built-in default instructions with the client-provided system prompt. @@ -7252,7 +7383,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d 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. +Optional. Omitted and `null` are equivalent and mean the agent is not reporting a stop reason; a malformed value is treated the same way. See protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/v2/draft/prompt-lifecycle#stop-reasons) @@ -7264,7 +7395,7 @@ This capability is not part of the spec yet, and may be removed or changed at an Token usage for completed foreground work. -Optional. Omitted or `null` both mean the agent is not reporting token +Optional. Omitted and `null` are equivalent and mean the agent is not reporting token usage for this state update. @@ -7356,7 +7487,7 @@ insertion, the prompt's response remains successful. Error | null} > The failure, as a JSON-RPC error object. -Optional. Omitted or `null` both mean the agent is not reporting failure details. +Optional. Omitted and `null` are equivalent and mean the agent is not reporting failure details. Agents SHOULD include it. @@ -7790,6 +7921,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Cost | null} > Cumulative session cost (optional). + +Omitted and `null` are equivalent and mean no cost is reported. + The discriminator value. Must be `"usage_update"`. @@ -8173,7 +8307,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d 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. +Optional. Omitted and `null` are equivalent and mean the agent is not reporting a stop reason; a malformed value is treated the same way. See protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/v2/draft/prompt-lifecycle#stop-reasons) @@ -8185,7 +8319,7 @@ This capability is not part of the spec yet, and may be removed or changed at an Token usage for completed foreground work. -Optional. Omitted or `null` both mean the agent is not reporting token +Optional. Omitted and `null` are equivalent and mean the agent is not reporting token usage for this state update. @@ -8277,7 +8411,7 @@ insertion, the prompt's response remains successful. Error | null} > The failure, as a JSON-RPC error object. -Optional. Omitted or `null` both mean the agent is not reporting failure details. +Optional. Omitted and `null` are equivalent and mean the agent is not reporting failure details. Agents SHOULD include it. @@ -8548,7 +8682,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d SessionCancelCapabilities | null} > Permits the client to cancel this child's current work without ending -the session. Omitted or `null` means unsupported; an object (including +the session. Omitted and `null` are equivalent and mean unsupported; an object (including `\{\}`) means supported. @@ -8979,6 +9113,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Annotations | null} > Optional annotations that help clients decide how to display or route this content. + +Omitted and `null` are equivalent and mean no annotations are provided. + Text payload carried by this content block. @@ -9002,6 +9139,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d MediaType | null} > MIME type describing the encoded media payload. + +Omitted and `null` are equivalent and mean the MIME type is not specified. + Text payload carried by this content block. @@ -9089,8 +9229,8 @@ Clients can use this field without parsing patch text to determine affected path DiffPatch | null} > Renderable patch text for some or all of the structured changes. -Agents SHOULD provide patch text whenever feasible. Omitted or `null` -means no renderable patch text was provided. +Agents SHOULD provide patch text whenever feasible. Omitted and `null` are +equivalent and mean no renderable patch text was provided. @@ -9476,12 +9616,16 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Total cache read tokens. +Omitted and `null` are equivalent and mean the count is not reported. + - Minimum: `0` Total cache write tokens. +Omitted and `null` are equivalent and mean the count is not reported. + - Minimum: `0` @@ -9500,6 +9644,8 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Total thought/reasoning tokens +Omitted and `null` are equivalent and mean the count is not reported. + - Minimum: `0` @@ -9528,6 +9674,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Cost | null} > Cumulative session cost (optional). + +Omitted and `null` are equivalent and mean no cost is reported. + Total context window size in tokens. diff --git a/docs/protocol/v2/overview.mdx b/docs/protocol/v2/overview.mdx index cc6a89ec0..0b89b721e 100644 --- a/docs/protocol/v2/overview.mdx +++ b/docs/protocol/v2/overview.mdx @@ -221,6 +221,8 @@ See [Errors](/protocol/v2/error) for the error codes ACP uses and when to use th Unless explicitly defined otherwise in the schema, ACP-defined JSON object property keys use `camelCase`. String values carried by discriminator fields use `snake_case`. The JSON-RPC envelope fields (`jsonrpc`, `id`, `method`, `params`, `result`, and `error`) follow the JSON-RPC 2.0 specification. +An optional field that is omitted and the same field set to `null` are equivalent, unless the field says otherwise. Upsert updates are the exception: there an omitted field leaves the stored value unchanged and `null` clears it. + Selected enum-like fields and tagged unions can define custom or future fallbacks. For those fields, `_`-prefixed values are reserved for implementation-specific extensions, while unknown non-underscore values are reserved for future ACP variants. ## Extensibility diff --git a/docs/protocol/v2/schema.mdx b/docs/protocol/v2/schema.mdx index 4194f40c8..e376283f5 100644 --- a/docs/protocol/v2/schema.mdx +++ b/docs/protocol/v2/schema.mdx @@ -406,9 +406,15 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e SessionListCursor | null} > Opaque cursor token from a previous response's nextCursor field for cursor-based pagination + +Omitted and `null` are equivalent and mean the first page is requested. + AbsolutePath | null} > Filter sessions by working directory. Must be an absolute path. + +Omitted and `null` are equivalent and mean sessions are not filtered by working directory. + #### ListSessionsResponse @@ -672,7 +678,7 @@ the request `cwd` matches the session's `cwd`. ReplayFrom | null} > Inclusive cursor describing where conversation replay should begin. -Optional. Omitted or `null` both mean the Agent should resume without +Optional. Omitted and `null` are equivalent and mean the Agent should resume without replaying previous conversation history. Replay cursors are inclusive: replay includes the position identified by the cursor. Supplying `\{ "type": "start" \}` means the Agent should replay all retained @@ -1129,8 +1135,11 @@ The user accepted and provided content. The discriminator value. Must be `"accept"`. - + The user-provided content, if any, as an object matching the requested schema. + +Omitted and `null` are equivalent and mean no content is provided. + @@ -1223,7 +1232,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Optional human-readable explanation of why permission is needed. This text is specific to the permission prompt and does not update any -subject's displayed content. Omitted or `null` both mean no separate +subject's displayed content. Omitted and `null` are equivalent and mean no separate permission description was provided. @@ -1237,7 +1246,7 @@ Must contain at least one option. RequestPermissionSubject | null} > Optional structured context about the operation requiring permission. -Omitted or `null` both mean no structured subject was provided. +Omitted and `null` are equivalent and mean no structured subject was provided. @@ -1413,7 +1422,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e AgentAuthCapabilities | null} > Authentication-related extension capabilities supported by the agent. -Optional. Omitted or `null` both mean the agent does not advertise any +Optional. Omitted and `null` are equivalent and mean the agent does not advertise any authentication-related extensions. This field does not advertise support for `auth/login` or `auth/logout`; those methods are advertised by a non-empty `authMethods` list in the `initialize` response. @@ -1422,7 +1431,7 @@ non-empty `authMethods` list in the `initialize` response. SessionCapabilities | null} > Session capabilities supported by the agent. -Optional. Omitted or `null` both mean the agent does not support the +Optional. Omitted and `null` are equivalent and mean the agent does not support the `session/*` method surface. Supplying `\{\}` means the agent supports the baseline session methods: `session/new`, `session/list`, `session/resume`, `session/close`, `session/prompt`, `session/cancel`, @@ -1524,18 +1533,25 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Role[] | null} > Intended recipients for this content, such as the user or assistant. + +Omitted and `null` are equivalent and mean no audience is specified. + Timestamp indicating when the underlying resource was last modified. Must be an RFC 3339 formatted string (e.g., "2025-01-12T15:00:58Z"). +Omitted and `null` are equivalent and mean the modification time is not reported. + - Format: `date-time` Relative importance of this content when clients choose what to surface. +Omitted and `null` are equivalent and mean no priority is specified. + | Constraint | Value | | ---------- | ----- | | Minimum | `0` | @@ -1561,6 +1577,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Annotations | null} > Optional annotations that help clients decide how to display or route this content. + +Omitted and `null` are equivalent and mean no annotations are provided. + Base64-encoded media payload. @@ -1599,6 +1618,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Optional description providing more details about this authentication method. + +Omitted and `null` are equivalent and mean no description is provided. + EnvVariable[]} > Additional environment variables to set on the configured agent invocation for terminal auth. @@ -1635,6 +1657,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Optional description providing more details about this authentication method. + +Omitted and `null` are equivalent and mean no description is provided. + AuthMethodId} required> Unique identifier for this authentication method. @@ -1700,6 +1725,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Optional description providing more details about this authentication method. + +Omitted and `null` are equivalent and mean no description is provided. + AuthMethodId} required> Unique identifier for this authentication method. @@ -1741,6 +1769,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Optional description providing more details about this authentication method. + +Omitted and `null` are equivalent and mean no description is provided. + EnvVariable[]} > Additional environment variables to set on the configured agent invocation for terminal auth. @@ -1780,6 +1811,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e AvailableCommandInput | null} > Input for the command if required + +Omitted and `null` are equivalent and mean the command takes no input. + Command name (e.g., `create_plan`, `research_codebase`). @@ -1922,6 +1956,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e MediaType | null} > MIME type describing the encoded media payload. + +Omitted and `null` are equivalent and mean the MIME type is not specified. + URI associated with this resource or media payload. @@ -2005,7 +2042,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e TerminalAuthCapabilities | null} > Whether the client supports `terminal` authentication methods. -Optional. Omitted or `null` both mean the client does not advertise support. +Optional. Omitted and `null` are equivalent and mean the client does not advertise support. The client should supply `\{\}` only when it can reproduce the configured agent invocation in an interactive terminal. Supplying `\{\}` means the agent may include `terminal` entries in its authentication methods. @@ -2038,7 +2075,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Determines which authentication method types the agent may include in its `InitializeResponse`. -Optional. Omitted or `null` both mean the client does not advertise any +Optional. Omitted and `null` are equivalent and mean the client does not advertise any authentication-method extensions. @@ -2046,7 +2083,7 @@ authentication-method extensions. Elicitation capabilities supported by the client. Determines which elicitation modes the agent may use. -Optional. Omitted or `null` both mean the client does not advertise +Optional. Omitted and `null` are equivalent and mean the client does not advertise elicitation support. @@ -2074,6 +2111,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e AvailableCommandInput | null} > Input for the command if required + +Omitted and `null` are equivalent and mean the command takes no input. + Command name (e.g., `create_plan`, `research_codebase`). @@ -2287,6 +2327,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Annotations | null} > Optional annotations that help clients decide how to display or route this content. + +Omitted and `null` are equivalent and mean no annotations are provided. + Text payload carried by this content block. @@ -2315,6 +2358,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Annotations | null} > Optional annotations that help clients decide how to display or route this content. + +Omitted and `null` are equivalent and mean no annotations are provided. + Base64-encoded media payload. @@ -2331,6 +2377,8 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e URI associated with this resource or media payload. +Omitted and `null` are equivalent and mean no URI is associated with the image. + - Format: `uri` @@ -2355,6 +2403,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Annotations | null} > Optional annotations that help clients decide how to display or route this content. + +Omitted and `null` are equivalent and mean no annotations are provided. + Base64-encoded media payload. @@ -2389,15 +2440,27 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Annotations | null} > Optional annotations that help clients decide how to display or route this content. + +Omitted and `null` are equivalent and mean no annotations are provided. + Optional human-readable details shown with this protocol object. + +Omitted and `null` are equivalent and mean no description is provided. + Icon[] | null} > Optional set of sized icons that the client can display in a user interface. + +Omitted and `null` are equivalent and mean no icons are provided. + MediaType | null} > MIME type describing the encoded media payload. + +Omitted and `null` are equivalent and mean the MIME type is not specified. + Human-readable name shown for this protocol object. @@ -2405,11 +2468,16 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Optional size of the linked resource in bytes, if known. +Omitted and `null` are equivalent and mean the size is not known. + - Minimum: `0` Optional display title for end-user UI. + +Omitted and `null` are equivalent and mean no title is provided. + The discriminator value. Must be `"resource_link"`. @@ -2443,6 +2511,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Annotations | null} > Optional annotations that help clients decide how to display or route this content. + +Omitted and `null` are equivalent and mean no annotations are provided. + EmbeddedResourceResource} required> Embedded resource payload, either text or binary data. @@ -2567,8 +2638,8 @@ Clients can use this field without parsing patch text to determine affected path DiffPatch | null} > Renderable patch text for some or all of the structured changes. -Agents SHOULD provide patch text whenever feasible. Omitted or `null` -means no renderable patch text was provided. +Agents SHOULD provide patch text whenever feasible. Omitted and `null` are +equivalent and mean no renderable patch text was provided. @@ -2594,13 +2665,13 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e DiffFileType | null} > File content kind after the operation (for `delete`, of the deleted file). -Omitted or `null` means the content kind is unknown. +Omitted and `null` are equivalent and mean the content kind is unknown. MediaType | null} > MIME type of the file contents after the operation (for `delete`, of the deleted file). -Omitted or `null` means the MIME type is unknown. +Omitted and `null` are equivalent and mean the MIME type is unknown. @@ -2866,8 +2937,11 @@ The user accepted the elicitation and provided content. **Properties:** - + The user-provided content, if any, as an object matching the requested schema. + +Omitted and `null` are equivalent and mean no content is provided. + ## ElicitationCapabilities @@ -2896,7 +2970,7 @@ Supplying `\{\}` explicitly advertises form support. ElicitationUrlCapabilities | null} > Whether the client supports URL-based elicitation. -Optional. Omitted or `null` both mean the client does not advertise support. +Optional. Omitted and `null` are equivalent and mean the client does not advertise support. Supplying `\{\}` means the client supports URL-based elicitation. @@ -3510,6 +3584,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Annotations | null} > Optional annotations that help clients decide how to display or route this content. + +Omitted and `null` are equivalent and mean no annotations are provided. + EmbeddedResourceResource} required> Embedded resource payload, either text or binary data. @@ -3536,6 +3613,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e MediaType | null} > MIME type describing the encoded media payload. + +Omitted and `null` are equivalent and mean the MIME type is not specified. + Text payload carried by this content block. @@ -3571,6 +3651,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e MediaType | null} > MIME type describing the encoded media payload. + +Omitted and `null` are equivalent and mean the MIME type is not specified. + URI associated with this resource or media payload. @@ -3648,17 +3731,19 @@ See protocol docs: [JSON-RPC Error Object](https://www.jsonrpc.org/specification **Properties:** ErrorCode} required> - A number indicating the error type that occurred. This must be an integer as - defined in the JSON-RPC specification. + A number indicating the error type that occurred. +This must be an integer as defined in the JSON-RPC specification. - - Optional primitive or structured value that contains additional information - about the error. This may include debugging information or context-specific - details. + + Optional primitive or structured value that contains additional information about the error. +This may include debugging information or context-specific details. + +Omitted and `null` are equivalent and mean no additional data is provided. + - A string providing a short description of the error. The message should be - limited to a concise single sentence. + A string providing a short description of the error. +The message should be limited to a concise single sentence. ## ErrorCode @@ -3728,7 +3813,7 @@ Details of a failure that ended active work. Error | null} > The failure, as a JSON-RPC error object. -Optional. Omitted or `null` both mean the agent is not reporting failure details. +Optional. Omitted and `null` are equivalent and mean the agent is not reporting failure details. Agents SHOULD include it. @@ -3798,6 +3883,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e MediaType | null} > Optional MIME type override if the source MIME type is missing or generic. + +Omitted and `null` are equivalent and mean the source MIME type is used. + <>"string"[] | null} > Optional array of strings that specify sizes at which the icon can be used. @@ -3806,6 +3894,8 @@ Each string should be in `WxH` format (e.g., `"48x48"`, `"96x96"`) or If not provided, the client should assume that the icon can be used at any size. +Omitted and `null` are equivalent and mean no sizes are specified. + A standard URI pointing to an icon resource. @@ -3815,6 +3905,9 @@ If not provided, the client should assume that the icon can be used at any size. IconTheme | null} > Optional theme this icon is designed for. + +Omitted and `null` are equivalent and mean the icon is not theme-specific. + ## IconTheme @@ -3866,7 +3959,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e 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. +Optional. Omitted and `null` are equivalent and mean the agent is not reporting a stop reason; a malformed value is treated the same way. See protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#stop-reasons) @@ -3957,7 +4050,7 @@ insertion, the prompt's response remains successful. Error | null} > The failure, as a JSON-RPC error object. -Optional. Omitted or `null` both mean the agent is not reporting failure details. +Optional. Omitted and `null` are equivalent and mean the agent is not reporting failure details. Agents SHOULD include it. @@ -4017,6 +4110,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Annotations | null} > Optional annotations that help clients decide how to display or route this content. + +Omitted and `null` are equivalent and mean no annotations are provided. + Base64-encoded media payload. @@ -4030,6 +4126,8 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e URI associated with this resource or media payload. +Omitted and `null` are equivalent and mean no URI is associated with the image. + - Format: `uri` @@ -4062,6 +4160,8 @@ and easily understood. If not provided, the name should be used for display. +Omitted and `null` are equivalent and mean the `name` is used for display. + Version of the implementation. Can be displayed to the user or used @@ -4134,14 +4234,14 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e McpHttpCapabilities | null} > Agent supports `http` MCP servers. -Optional. Omitted or `null` both mean the agent does not advertise support. +Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports HTTP MCP server transports. McpStdioCapabilities | null} > Agent supports `stdio` MCP servers. -Optional. Omitted or `null` both mean the agent does not advertise support. +Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports stdio MCP server transports. @@ -4923,7 +5023,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e PromptAudioCapabilities | null} > Agent supports `audio` content blocks. -Optional. Omitted or `null` both mean the agent does not advertise support. +Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports audio content in prompts. @@ -4933,14 +5033,14 @@ Supplying `\{\}` means the agent supports audio content in prompts. When enabled, the Client is allowed to include `resource` content blocks in prompt requests for pieces of context that are referenced in the message. -Optional. Omitted or `null` both mean the agent does not advertise support. +Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports embedded context in prompts. PromptImageCapabilities | null} > Agent supports `image` content blocks. -Optional. Omitted or `null` both mean the agent does not advertise support. +Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports image content in prompts. @@ -5301,15 +5401,27 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Annotations | null} > Optional annotations that help clients decide how to display or route this content. + +Omitted and `null` are equivalent and mean no annotations are provided. + Optional human-readable details shown with this protocol object. + +Omitted and `null` are equivalent and mean no description is provided. + Icon[] | null} > Optional set of sized icons that the client can display in a user interface. + +Omitted and `null` are equivalent and mean no icons are provided. + MediaType | null} > MIME type describing the encoded media payload. + +Omitted and `null` are equivalent and mean the MIME type is not specified. + Human-readable name shown for this protocol object. @@ -5317,11 +5429,16 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Optional size of the linked resource in bytes, if known. +Omitted and `null` are equivalent and mean the size is not known. + - Minimum: `0` Optional display title for end-user UI. + +Omitted and `null` are equivalent and mean no title is provided. + URI associated with this resource or media payload. @@ -5441,7 +5558,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e SessionAdditionalDirectoriesCapabilities | null} > Whether the agent supports `additionalDirectories` on supported session lifecycle requests. -Optional. Omitted or `null` both mean the agent does not advertise support. +Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports `additionalDirectories` on supported session lifecycle requests. @@ -5452,21 +5569,21 @@ complete ordered additional-root list associated with a listed session. SessionDeleteCapabilities | null} > Whether the agent supports `session/delete`. -Optional. Omitted or `null` both mean the agent does not advertise support. +Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports deleting sessions from `session/list`. McpCapabilities | null} > MCP capabilities supported by the agent for session lifecycle requests. -Optional. Omitted or `null` both mean the agent does not advertise MCP +Optional. Omitted and `null` are equivalent and mean the agent does not advertise MCP server transport support for sessions. PromptCapabilities | null} > Prompt capabilities supported by the agent in `session/prompt` requests. -Optional. Omitted or `null` both mean the agent does not advertise any +Optional. Omitted and `null` are equivalent and mean the agent does not advertise any prompt extensions beyond the baseline text and resource-link content required by `session/prompt`. @@ -5514,12 +5631,18 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e SessionConfigOptionCategory | null} > Optional semantic category for this option (UX only). + +Omitted and `null` are equivalent and mean no category is provided. + SessionConfigId} required> Unique identifier for the configuration option. Optional description for the Client to display to the user. + +Omitted and `null` are equivalent and mean no description is provided. + Human-readable label for the option. @@ -5701,6 +5824,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Optional description for this option value. + +Omitted and `null` are equivalent and mean no description is provided. + Human-readable label for this option value. @@ -5791,10 +5917,15 @@ reports no additional roots. Human-readable title for the session + +Omitted and `null` are equivalent and mean no title is provided. + RFC 3339 timestamp of last activity. +Omitted and `null` are equivalent and mean the last activity time is not reported. + - Format: `date-time` @@ -6095,7 +6226,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e 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. +Optional. Omitted and `null` are equivalent and mean the agent is not reporting a stop reason; a malformed value is treated the same way. See protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#stop-reasons) @@ -6188,7 +6319,7 @@ insertion, the prompt's response remains successful. Error | null} > The failure, as a JSON-RPC error object. -Optional. Omitted or `null` both mean the agent is not reporting failure details. +Optional. Omitted and `null` are equivalent and mean the agent is not reporting failure details. Agents SHOULD include it. @@ -6570,6 +6701,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Cost | null} > Cumulative session cost (optional). + +Omitted and `null` are equivalent and mean no cost is reported. + The discriminator value. Must be `"usage_update"`. @@ -6799,7 +6933,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e 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. +Optional. Omitted and `null` are equivalent and mean the agent is not reporting a stop reason; a malformed value is treated the same way. See protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#stop-reasons) @@ -6892,7 +7026,7 @@ insertion, the prompt's response remains successful. Error | null} > The failure, as a JSON-RPC error object. -Optional. Omitted or `null` both mean the agent is not reporting failure details. +Optional. Omitted and `null` are equivalent and mean the agent is not reporting failure details. Agents SHOULD include it. @@ -7366,6 +7500,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Annotations | null} > Optional annotations that help clients decide how to display or route this content. + +Omitted and `null` are equivalent and mean no annotations are provided. + Text payload carried by this content block. @@ -7389,6 +7526,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e MediaType | null} > MIME type describing the encoded media payload. + +Omitted and `null` are equivalent and mean the MIME type is not specified. + Text payload carried by this content block. @@ -7476,8 +7616,8 @@ Clients can use this field without parsing patch text to determine affected path DiffPatch | null} > Renderable patch text for some or all of the structured changes. -Agents SHOULD provide patch text whenever feasible. Omitted or `null` -means no renderable patch text was provided. +Agents SHOULD provide patch text whenever feasible. Omitted and `null` are +equivalent and mean no renderable patch text was provided. @@ -7829,6 +7969,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Cost | null} > Cumulative session cost (optional). + +Omitted and `null` are equivalent and mean no cost is reported. + Total context window size in tokens. diff --git a/schema/v2/schema.json b/schema/v2/schema.json index e5a7412ef..b3b0597b2 100644 --- a/schema/v2/schema.json +++ b/schema/v2/schema.json @@ -570,12 +570,12 @@ "type": "string" }, "description": { - "description": "Optional human-readable explanation of why permission is needed.\n\nThis text is specific to the permission prompt and does not update any\nsubject's displayed content. Omitted or `null` both mean no separate\npermission description was provided.", + "description": "Optional human-readable explanation of why permission is needed.\n\nThis text is specific to the permission prompt and does not update any\nsubject's displayed content. Omitted and `null` are equivalent and mean no separate\npermission description was provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "subject": { - "description": "Optional structured context about the operation requiring permission.\n\nOmitted or `null` both mean no structured subject was provided.", + "description": "Optional structured context about the operation requiring permission.\n\nOmitted and `null` are equivalent and mean no structured subject was provided.", "anyOf": [ { "$ref": "#/$defs/RequestPermissionSubject" @@ -1119,7 +1119,7 @@ "type": "object", "properties": { "audience": { - "description": "Intended recipients for this content, such as the user or assistant.", + "description": "Intended recipients for this content, such as the user or assistant.\n\nOmitted and `null` are equivalent and mean no audience is specified.", "type": ["array", "null"], "items": { "$ref": "#/$defs/Role" @@ -1128,13 +1128,13 @@ "x-deserialize-skip-invalid-items": true }, "lastModified": { - "description": "Timestamp indicating when the underlying resource was last modified.\n\nMust be an RFC 3339 formatted string (e.g., \"2025-01-12T15:00:58Z\").", + "description": "Timestamp indicating when the underlying resource was last modified.\n\nMust be an RFC 3339 formatted string (e.g., \"2025-01-12T15:00:58Z\").\n\nOmitted and `null` are equivalent and mean the modification time is not reported.", "type": ["string", "null"], "format": "date-time", "x-deserialize-default-on-error": true }, "priority": { - "description": "Relative importance of this content when clients choose what to surface.", + "description": "Relative importance of this content when clients choose what to surface.\n\nOmitted and `null` are equivalent and mean no priority is specified.", "type": ["number", "null"], "format": "double", "minimum": 0, @@ -1178,7 +1178,7 @@ "type": "string" }, "annotations": { - "description": "Optional annotations that help clients decide how to display or route this content.", + "description": "Optional annotations that help clients decide how to display or route this content.\n\nOmitted and `null` are equivalent and mean no annotations are provided.", "anyOf": [ { "$ref": "#/$defs/Annotations" @@ -1220,13 +1220,13 @@ ] }, "uri": { - "description": "URI associated with this resource or media payload.", + "description": "URI associated with this resource or media payload.\n\nOmitted and `null` are equivalent and mean no URI is associated with the image.", "type": ["string", "null"], "format": "uri", "x-deserialize-default-on-error": true }, "annotations": { - "description": "Optional annotations that help clients decide how to display or route this content.", + "description": "Optional annotations that help clients decide how to display or route this content.\n\nOmitted and `null` are equivalent and mean no annotations are provided.", "anyOf": [ { "$ref": "#/$defs/Annotations" @@ -1264,7 +1264,7 @@ ] }, "annotations": { - "description": "Optional annotations that help clients decide how to display or route this content.", + "description": "Optional annotations that help clients decide how to display or route this content.\n\nOmitted and `null` are equivalent and mean no annotations are provided.", "anyOf": [ { "$ref": "#/$defs/Annotations" @@ -1294,7 +1294,7 @@ "format": "uri" }, "mimeType": { - "description": "Optional MIME type override if the source MIME type is missing or generic.", + "description": "Optional MIME type override if the source MIME type is missing or generic.\n\nOmitted and `null` are equivalent and mean the source MIME type is used.", "anyOf": [ { "$ref": "#/$defs/MediaType" @@ -1306,7 +1306,7 @@ "x-deserialize-default-on-error": true }, "sizes": { - "description": "Optional array of strings that specify sizes at which the icon can be used.\nEach string should be in `WxH` format (e.g., `\"48x48\"`, `\"96x96\"`) or\n`\"any\"` for scalable formats like SVG.\n\nIf not provided, the client should assume that the icon can be used at any size.", + "description": "Optional array of strings that specify sizes at which the icon can be used.\nEach string should be in `WxH` format (e.g., `\"48x48\"`, `\"96x96\"`) or\n`\"any\"` for scalable formats like SVG.\n\nIf not provided, the client should assume that the icon can be used at any size.\n\nOmitted and `null` are equivalent and mean no sizes are specified.", "type": ["array", "null"], "items": { "type": "string" @@ -1315,7 +1315,7 @@ "x-deserialize-skip-invalid-items": true }, "theme": { - "description": "Optional theme this icon is designed for.", + "description": "Optional theme this icon is designed for.\n\nOmitted and `null` are equivalent and mean the icon is not theme-specific.", "anyOf": [ { "$ref": "#/$defs/IconTheme" @@ -1369,17 +1369,17 @@ "format": "uri" }, "title": { - "description": "Optional display title for end-user UI.", + "description": "Optional display title for end-user UI.\n\nOmitted and `null` are equivalent and mean no title is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "description": { - "description": "Optional human-readable details shown with this protocol object.", + "description": "Optional human-readable details shown with this protocol object.\n\nOmitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "icons": { - "description": "Optional set of sized icons that the client can display in a user interface.", + "description": "Optional set of sized icons that the client can display in a user interface.\n\nOmitted and `null` are equivalent and mean no icons are provided.", "type": ["array", "null"], "items": { "$ref": "#/$defs/Icon" @@ -1388,7 +1388,7 @@ "x-deserialize-skip-invalid-items": true }, "mimeType": { - "description": "MIME type describing the encoded media payload.", + "description": "MIME type describing the encoded media payload.\n\nOmitted and `null` are equivalent and mean the MIME type is not specified.", "anyOf": [ { "$ref": "#/$defs/MediaType" @@ -1400,14 +1400,14 @@ "x-deserialize-default-on-error": true }, "size": { - "description": "Optional size of the linked resource in bytes, if known.", + "description": "Optional size of the linked resource in bytes, if known.\n\nOmitted and `null` are equivalent and mean the size is not known.", "type": ["integer", "null"], "format": "uint64", "minimum": 0, "x-deserialize-default-on-error": true }, "annotations": { - "description": "Optional annotations that help clients decide how to display or route this content.", + "description": "Optional annotations that help clients decide how to display or route this content.\n\nOmitted and `null` are equivalent and mean no annotations are provided.", "anyOf": [ { "$ref": "#/$defs/Annotations" @@ -1464,7 +1464,7 @@ "format": "uri" }, "mimeType": { - "description": "MIME type describing the encoded media payload.", + "description": "MIME type describing the encoded media payload.\n\nOmitted and `null` are equivalent and mean the MIME type is not specified.", "anyOf": [ { "$ref": "#/$defs/MediaType" @@ -1499,7 +1499,7 @@ "format": "uri" }, "mimeType": { - "description": "MIME type describing the encoded media payload.", + "description": "MIME type describing the encoded media payload.\n\nOmitted and `null` are equivalent and mean the MIME type is not specified.", "anyOf": [ { "$ref": "#/$defs/MediaType" @@ -1532,7 +1532,7 @@ ] }, "annotations": { - "description": "Optional annotations that help clients decide how to display or route this content.", + "description": "Optional annotations that help clients decide how to display or route this content.\n\nOmitted and `null` are equivalent and mean no annotations are provided.", "anyOf": [ { "$ref": "#/$defs/Annotations" @@ -1578,7 +1578,7 @@ "type": "object", "properties": { "fileType": { - "description": "File content kind after the operation (for `delete`, of the deleted file).\n\nOmitted or `null` means the content kind is unknown.", + "description": "File content kind after the operation (for `delete`, of the deleted file).\n\nOmitted and `null` are equivalent and mean the content kind is unknown.", "anyOf": [ { "$ref": "#/$defs/DiffFileType" @@ -1590,7 +1590,7 @@ "x-deserialize-default-on-error": true }, "mimeType": { - "description": "MIME type of the file contents after the operation (for `delete`, of the deleted file).\n\nOmitted or `null` means the MIME type is unknown.", + "description": "MIME type of the file contents after the operation (for `delete`, of the deleted file).\n\nOmitted and `null` are equivalent and mean the MIME type is unknown.", "anyOf": [ { "$ref": "#/$defs/MediaType" @@ -1883,7 +1883,7 @@ "x-deserialize-skip-invalid-items": true }, "patch": { - "description": "Renderable patch text for some or all of the structured changes.\n\nAgents SHOULD provide patch text whenever feasible. Omitted or `null`\nmeans no renderable patch text was provided.", + "description": "Renderable patch text for some or all of the structured changes.\n\nAgents SHOULD provide patch text whenever feasible. Omitted and `null` are\nequivalent and mean no renderable patch text was provided.", "anyOf": [ { "$ref": "#/$defs/DiffPatch" @@ -3140,7 +3140,7 @@ "type": "string" }, "title": { - "description": "Intended for UI and end-user contexts — 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 — optimized to be human-readable\nand easily understood.\n\nIf not provided, the name should be used for display.\n\nOmitted and `null` are equivalent and mean the `name` is used for display.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, @@ -3162,7 +3162,7 @@ "type": "object", "properties": { "session": { - "description": "Session capabilities supported by the agent.\n\nOptional. Omitted or `null` both mean the agent does not support the\n`session/*` method surface. Supplying `{}` means the agent supports the\nbaseline session methods: `session/new`, `session/list`,\n`session/resume`, `session/close`, `session/prompt`, `session/cancel`,\nand `session/update`.", + "description": "Session capabilities supported by the agent.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not support the\n`session/*` method surface. Supplying `{}` means the agent supports the\nbaseline session methods: `session/new`, `session/list`,\n`session/resume`, `session/close`, `session/prompt`, `session/cancel`,\nand `session/update`.", "anyOf": [ { "$ref": "#/$defs/SessionCapabilities" @@ -3174,7 +3174,7 @@ "x-deserialize-default-on-error": true }, "auth": { - "description": "Authentication-related extension capabilities supported by the agent.\n\nOptional. Omitted or `null` both mean the agent does not advertise any\nauthentication-related extensions. This field does not advertise support\nfor `auth/login` or `auth/logout`; those methods are advertised by a\nnon-empty `authMethods` list in the `initialize` response.", + "description": "Authentication-related extension capabilities supported by the agent.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise any\nauthentication-related extensions. This field does not advertise support\nfor `auth/login` or `auth/logout`; those methods are advertised by a\nnon-empty `authMethods` list in the `initialize` response.", "anyOf": [ { "$ref": "#/$defs/AgentAuthCapabilities" @@ -3198,7 +3198,7 @@ "type": "object", "properties": { "prompt": { - "description": "Prompt capabilities supported by the agent in `session/prompt` requests.\n\nOptional. Omitted or `null` both mean the agent does not advertise any\nprompt extensions beyond the baseline text and resource-link content\nrequired by `session/prompt`.", + "description": "Prompt capabilities supported by the agent in `session/prompt` requests.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise any\nprompt extensions beyond the baseline text and resource-link content\nrequired by `session/prompt`.", "anyOf": [ { "$ref": "#/$defs/PromptCapabilities" @@ -3210,7 +3210,7 @@ "x-deserialize-default-on-error": true }, "mcp": { - "description": "MCP capabilities supported by the agent for session lifecycle requests.\n\nOptional. Omitted or `null` both mean the agent does not advertise MCP\nserver transport support for sessions.", + "description": "MCP capabilities supported by the agent for session lifecycle requests.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise MCP\nserver transport support for sessions.", "anyOf": [ { "$ref": "#/$defs/McpCapabilities" @@ -3222,7 +3222,7 @@ "x-deserialize-default-on-error": true }, "delete": { - "description": "Whether the agent supports `session/delete`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports deleting sessions from `session/list`.", + "description": "Whether the agent supports `session/delete`.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise support.\nSupplying `{}` means the agent supports deleting sessions from `session/list`.", "anyOf": [ { "$ref": "#/$defs/SessionDeleteCapabilities" @@ -3234,7 +3234,7 @@ "x-deserialize-default-on-error": true }, "additionalDirectories": { - "description": "Whether the agent supports `additionalDirectories` on supported session lifecycle requests.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports `additionalDirectories` on\nsupported session lifecycle requests.\n\nAgents may return `SessionInfo.additionalDirectories` to report the\ncomplete ordered additional-root list associated with a listed session.", + "description": "Whether the agent supports `additionalDirectories` on supported session lifecycle requests.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise support.\nSupplying `{}` means the agent supports `additionalDirectories` on\nsupported session lifecycle requests.\n\nAgents may return `SessionInfo.additionalDirectories` to report the\ncomplete ordered additional-root list associated with a listed session.", "anyOf": [ { "$ref": "#/$defs/SessionAdditionalDirectoriesCapabilities" @@ -3258,7 +3258,7 @@ "type": "object", "properties": { "image": { - "description": "Agent supports `image` content blocks.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports image content in prompts.", + "description": "Agent supports `image` content blocks.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise support.\nSupplying `{}` means the agent supports image content in prompts.", "anyOf": [ { "$ref": "#/$defs/PromptImageCapabilities" @@ -3270,7 +3270,7 @@ "x-deserialize-default-on-error": true }, "audio": { - "description": "Agent supports `audio` content blocks.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports audio content in prompts.", + "description": "Agent supports `audio` content blocks.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise support.\nSupplying `{}` means the agent supports audio content in prompts.", "anyOf": [ { "$ref": "#/$defs/PromptAudioCapabilities" @@ -3282,7 +3282,7 @@ "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 `resource` content blocks\nin prompt requests for pieces of context that are referenced in the message.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports embedded context in prompts.", + "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.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise support.\nSupplying `{}` means the agent supports embedded context in prompts.", "anyOf": [ { "$ref": "#/$defs/PromptEmbeddedContextCapabilities" @@ -3342,7 +3342,7 @@ "type": "object", "properties": { "stdio": { - "description": "Agent supports `stdio` MCP servers.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports stdio MCP server transports.", + "description": "Agent supports `stdio` MCP servers.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise support.\nSupplying `{}` means the agent supports stdio MCP server transports.", "anyOf": [ { "$ref": "#/$defs/McpStdioCapabilities" @@ -3354,7 +3354,7 @@ "x-deserialize-default-on-error": true }, "http": { - "description": "Agent supports `http` MCP servers.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports HTTP MCP server transports.", + "description": "Agent supports `http` MCP servers.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise support.\nSupplying `{}` means the agent supports HTTP MCP server transports.", "anyOf": [ { "$ref": "#/$defs/McpHttpCapabilities" @@ -3561,7 +3561,7 @@ "type": "string" }, "description": { - "description": "Optional description providing more details about this authentication method.", + "description": "Optional description providing more details about this authentication method.\n\nOmitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, @@ -3605,7 +3605,7 @@ "type": "string" }, "description": { - "description": "Optional description providing more details about this authentication method.", + "description": "Optional description providing more details about this authentication method.\n\nOmitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, @@ -3704,12 +3704,12 @@ "type": "string" }, "description": { - "description": "Optional description for the Client to display to the user.", + "description": "Optional description for the Client to display to the user.\n\nOmitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "category": { - "description": "Optional semantic category for this option (UX only).", + "description": "Optional semantic category for this option (UX only).\n\nOmitted and `null` are equivalent and mean no category is provided.", "anyOf": [ { "$ref": "#/$defs/SessionConfigOptionCategory" @@ -3876,7 +3876,7 @@ "type": "string" }, "description": { - "description": "Optional description for this option value.", + "description": "Optional description for this option value.\n\nOmitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, @@ -4095,7 +4095,7 @@ "type": "string" }, "input": { - "description": "Input for the command if required", + "description": "Input for the command if required\n\nOmitted and `null` are equivalent and mean the command takes no input.", "anyOf": [ { "$ref": "#/$defs/AvailableCommandInput" @@ -4181,12 +4181,12 @@ "x-deserialize-skip-invalid-items": true }, "title": { - "description": "Human-readable title for the session", + "description": "Human-readable title for the session\n\nOmitted and `null` are equivalent and mean no title is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "updatedAt": { - "description": "RFC 3339 timestamp of last activity.", + "description": "RFC 3339 timestamp of last activity.\n\nOmitted and `null` are equivalent and mean the last activity time is not reported.", "type": ["string", "null"], "format": "date-time", "x-deserialize-default-on-error": true @@ -4335,7 +4335,7 @@ "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.", + "description": "Optional primitive or structured value that contains additional information about the error.\nThis may include debugging information or context-specific details.\n\nOmitted and `null` are equivalent and mean no additional data is provided.", "x-deserialize-default-on-error": true } }, @@ -5150,7 +5150,7 @@ "type": "object", "properties": { "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.", + "description": "The failure, as a JSON-RPC error object.\n\nOptional. Omitted and `null` are equivalent and mean the agent is not reporting failure details.\nAgents SHOULD include it.", "anyOf": [ { "$ref": "#/$defs/Error" @@ -5174,7 +5174,7 @@ "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: [Stop Reasons](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#stop-reasons)", + "description": "Why foreground work stopped. The value selects one of this type's variants, which may add fields of their own.\n\nOptional. Omitted and `null` are equivalent and mean the agent is not reporting a stop reason; a malformed value is treated the same way.\n\nSee protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/v2/prompt-lifecycle#stop-reasons)", "type": ["string", "null"], "x-deserialize-default-on-error": true } @@ -5955,7 +5955,7 @@ "minimum": 0 }, "cost": { - "description": "Cumulative session cost (optional).", + "description": "Cumulative session cost (optional).\n\nOmitted and `null` are equivalent and mean no cost is reported.", "anyOf": [ { "$ref": "#/$defs/Cost" @@ -6341,7 +6341,7 @@ "type": "object", "properties": { "auth": { - "description": "Authentication capabilities supported by the client.\nDetermines which authentication method types the agent may include\nin its `InitializeResponse`.\n\nOptional. Omitted or `null` both mean the client does not advertise any\nauthentication-method extensions.", + "description": "Authentication capabilities supported by the client.\nDetermines which authentication method types the agent may include\nin its `InitializeResponse`.\n\nOptional. Omitted and `null` are equivalent and mean the client does not advertise any\nauthentication-method extensions.", "anyOf": [ { "$ref": "#/$defs/ClientAuthCapabilities" @@ -6353,7 +6353,7 @@ "x-deserialize-default-on-error": true }, "elicitation": { - "description": "Elicitation capabilities supported by the client.\nDetermines which elicitation modes the agent may use.\n\nOptional. Omitted or `null` both mean the client does not advertise\nelicitation support.", + "description": "Elicitation capabilities supported by the client.\nDetermines which elicitation modes the agent may use.\n\nOptional. Omitted and `null` are equivalent and mean the client does not advertise\nelicitation support.", "anyOf": [ { "$ref": "#/$defs/ElicitationCapabilities" @@ -6377,7 +6377,7 @@ "type": "object", "properties": { "terminal": { - "description": "Whether the client supports `terminal` authentication methods.\n\nOptional. Omitted or `null` both mean the client does not advertise support.\nThe client should supply `{}` only when it can reproduce the configured\nagent invocation in an interactive terminal. Supplying `{}` means the\nagent may include `terminal` entries in its authentication methods.", + "description": "Whether the client supports `terminal` authentication methods.\n\nOptional. Omitted and `null` are equivalent and mean the client does not advertise support.\nThe client should supply `{}` only when it can reproduce the configured\nagent invocation in an interactive terminal. Supplying `{}` means the\nagent may include `terminal` entries in its authentication methods.", "anyOf": [ { "$ref": "#/$defs/TerminalAuthCapabilities" @@ -6425,7 +6425,7 @@ "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.", + "description": "Whether the client supports URL-based elicitation.\n\nOptional. Omitted and `null` are equivalent and mean the client does not advertise support.\nSupplying `{}` means the client supports URL-based elicitation.", "anyOf": [ { "$ref": "#/$defs/ElicitationUrlCapabilities" @@ -6710,7 +6710,7 @@ "type": "object", "properties": { "cwd": { - "description": "Filter sessions by working directory. Must be an absolute path.", + "description": "Filter sessions by working directory. Must be an absolute path.\n\nOmitted and `null` are equivalent and mean sessions are not filtered by working directory.", "anyOf": [ { "$ref": "#/$defs/AbsolutePath" @@ -6721,7 +6721,7 @@ ] }, "cursor": { - "description": "Opaque cursor token from a previous response's nextCursor field for cursor-based pagination", + "description": "Opaque cursor token from a previous response's nextCursor field for cursor-based pagination\n\nOmitted and `null` are equivalent and mean the first page is requested.", "anyOf": [ { "$ref": "#/$defs/SessionListCursor" @@ -6799,7 +6799,7 @@ } }, "replayFrom": { - "description": "Inclusive cursor describing where conversation replay should begin.\n\nOptional. Omitted or `null` both mean the Agent should resume without\nreplaying previous conversation history. Replay cursors are inclusive:\nreplay includes the position identified by the cursor. Supplying\n`{ \"type\": \"start\" }` means the Agent should replay all retained\nconversation history before responding.\n\nAgents MUST reject unsupported cursor types or malformed cursor values\nwith `-32602` (Invalid params), rather than substituting another cursor\nor resuming without replay.", + "description": "Inclusive cursor describing where conversation replay should begin.\n\nOptional. Omitted and `null` are equivalent and mean the Agent should resume without\nreplaying previous conversation history. Replay cursors are inclusive:\nreplay includes the position identified by the cursor. Supplying\n`{ \"type\": \"start\" }` means the Agent should replay all retained\nconversation history before responding.\n\nAgents MUST reject unsupported cursor types or malformed cursor values\nwith `-32602` (Invalid params), rather than substituting another cursor\nor resuming without replay.", "anyOf": [ { "$ref": "#/$defs/ReplayFrom" @@ -7397,7 +7397,7 @@ "type": "object", "properties": { "content": { - "description": "The user-provided content, if any, as an object matching the requested schema.", + "description": "The user-provided content, if any, as an object matching the requested schema.\n\nOmitted and `null` are equivalent and mean no content is provided.", "type": ["object", "null"], "additionalProperties": { "$ref": "#/$defs/ElicitationContentValue" diff --git a/schema/v2/schema.unstable.json b/schema/v2/schema.unstable.json index c2a9e691b..f37e9929a 100644 --- a/schema/v2/schema.unstable.json +++ b/schema/v2/schema.unstable.json @@ -624,12 +624,12 @@ "type": "string" }, "description": { - "description": "Optional human-readable explanation of why permission is needed.\n\nThis text is specific to the permission prompt and does not update any\nsubject's displayed content. Omitted or `null` both mean no separate\npermission description was provided.", + "description": "Optional human-readable explanation of why permission is needed.\n\nThis text is specific to the permission prompt and does not update any\nsubject's displayed content. Omitted and `null` are equivalent and mean no separate\npermission description was provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "subject": { - "description": "Optional structured context about the operation requiring permission.\n\nOmitted or `null` both mean no structured subject was provided.", + "description": "Optional structured context about the operation requiring permission.\n\nOmitted and `null` are equivalent and mean no structured subject was provided.", "anyOf": [ { "$ref": "#/$defs/RequestPermissionSubject" @@ -1173,7 +1173,7 @@ "type": "object", "properties": { "audience": { - "description": "Intended recipients for this content, such as the user or assistant.", + "description": "Intended recipients for this content, such as the user or assistant.\n\nOmitted and `null` are equivalent and mean no audience is specified.", "type": ["array", "null"], "items": { "$ref": "#/$defs/Role" @@ -1182,13 +1182,13 @@ "x-deserialize-skip-invalid-items": true }, "lastModified": { - "description": "Timestamp indicating when the underlying resource was last modified.\n\nMust be an RFC 3339 formatted string (e.g., \"2025-01-12T15:00:58Z\").", + "description": "Timestamp indicating when the underlying resource was last modified.\n\nMust be an RFC 3339 formatted string (e.g., \"2025-01-12T15:00:58Z\").\n\nOmitted and `null` are equivalent and mean the modification time is not reported.", "type": ["string", "null"], "format": "date-time", "x-deserialize-default-on-error": true }, "priority": { - "description": "Relative importance of this content when clients choose what to surface.", + "description": "Relative importance of this content when clients choose what to surface.\n\nOmitted and `null` are equivalent and mean no priority is specified.", "type": ["number", "null"], "format": "double", "minimum": 0, @@ -1232,7 +1232,7 @@ "type": "string" }, "annotations": { - "description": "Optional annotations that help clients decide how to display or route this content.", + "description": "Optional annotations that help clients decide how to display or route this content.\n\nOmitted and `null` are equivalent and mean no annotations are provided.", "anyOf": [ { "$ref": "#/$defs/Annotations" @@ -1274,13 +1274,13 @@ ] }, "uri": { - "description": "URI associated with this resource or media payload.", + "description": "URI associated with this resource or media payload.\n\nOmitted and `null` are equivalent and mean no URI is associated with the image.", "type": ["string", "null"], "format": "uri", "x-deserialize-default-on-error": true }, "annotations": { - "description": "Optional annotations that help clients decide how to display or route this content.", + "description": "Optional annotations that help clients decide how to display or route this content.\n\nOmitted and `null` are equivalent and mean no annotations are provided.", "anyOf": [ { "$ref": "#/$defs/Annotations" @@ -1318,7 +1318,7 @@ ] }, "annotations": { - "description": "Optional annotations that help clients decide how to display or route this content.", + "description": "Optional annotations that help clients decide how to display or route this content.\n\nOmitted and `null` are equivalent and mean no annotations are provided.", "anyOf": [ { "$ref": "#/$defs/Annotations" @@ -1348,7 +1348,7 @@ "format": "uri" }, "mimeType": { - "description": "Optional MIME type override if the source MIME type is missing or generic.", + "description": "Optional MIME type override if the source MIME type is missing or generic.\n\nOmitted and `null` are equivalent and mean the source MIME type is used.", "anyOf": [ { "$ref": "#/$defs/MediaType" @@ -1360,7 +1360,7 @@ "x-deserialize-default-on-error": true }, "sizes": { - "description": "Optional array of strings that specify sizes at which the icon can be used.\nEach string should be in `WxH` format (e.g., `\"48x48\"`, `\"96x96\"`) or\n`\"any\"` for scalable formats like SVG.\n\nIf not provided, the client should assume that the icon can be used at any size.", + "description": "Optional array of strings that specify sizes at which the icon can be used.\nEach string should be in `WxH` format (e.g., `\"48x48\"`, `\"96x96\"`) or\n`\"any\"` for scalable formats like SVG.\n\nIf not provided, the client should assume that the icon can be used at any size.\n\nOmitted and `null` are equivalent and mean no sizes are specified.", "type": ["array", "null"], "items": { "type": "string" @@ -1369,7 +1369,7 @@ "x-deserialize-skip-invalid-items": true }, "theme": { - "description": "Optional theme this icon is designed for.", + "description": "Optional theme this icon is designed for.\n\nOmitted and `null` are equivalent and mean the icon is not theme-specific.", "anyOf": [ { "$ref": "#/$defs/IconTheme" @@ -1423,17 +1423,17 @@ "format": "uri" }, "title": { - "description": "Optional display title for end-user UI.", + "description": "Optional display title for end-user UI.\n\nOmitted and `null` are equivalent and mean no title is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "description": { - "description": "Optional human-readable details shown with this protocol object.", + "description": "Optional human-readable details shown with this protocol object.\n\nOmitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "icons": { - "description": "Optional set of sized icons that the client can display in a user interface.", + "description": "Optional set of sized icons that the client can display in a user interface.\n\nOmitted and `null` are equivalent and mean no icons are provided.", "type": ["array", "null"], "items": { "$ref": "#/$defs/Icon" @@ -1442,7 +1442,7 @@ "x-deserialize-skip-invalid-items": true }, "mimeType": { - "description": "MIME type describing the encoded media payload.", + "description": "MIME type describing the encoded media payload.\n\nOmitted and `null` are equivalent and mean the MIME type is not specified.", "anyOf": [ { "$ref": "#/$defs/MediaType" @@ -1454,14 +1454,14 @@ "x-deserialize-default-on-error": true }, "size": { - "description": "Optional size of the linked resource in bytes, if known.", + "description": "Optional size of the linked resource in bytes, if known.\n\nOmitted and `null` are equivalent and mean the size is not known.", "type": ["integer", "null"], "format": "uint64", "minimum": 0, "x-deserialize-default-on-error": true }, "annotations": { - "description": "Optional annotations that help clients decide how to display or route this content.", + "description": "Optional annotations that help clients decide how to display or route this content.\n\nOmitted and `null` are equivalent and mean no annotations are provided.", "anyOf": [ { "$ref": "#/$defs/Annotations" @@ -1518,7 +1518,7 @@ "format": "uri" }, "mimeType": { - "description": "MIME type describing the encoded media payload.", + "description": "MIME type describing the encoded media payload.\n\nOmitted and `null` are equivalent and mean the MIME type is not specified.", "anyOf": [ { "$ref": "#/$defs/MediaType" @@ -1553,7 +1553,7 @@ "format": "uri" }, "mimeType": { - "description": "MIME type describing the encoded media payload.", + "description": "MIME type describing the encoded media payload.\n\nOmitted and `null` are equivalent and mean the MIME type is not specified.", "anyOf": [ { "$ref": "#/$defs/MediaType" @@ -1586,7 +1586,7 @@ ] }, "annotations": { - "description": "Optional annotations that help clients decide how to display or route this content.", + "description": "Optional annotations that help clients decide how to display or route this content.\n\nOmitted and `null` are equivalent and mean no annotations are provided.", "anyOf": [ { "$ref": "#/$defs/Annotations" @@ -1632,7 +1632,7 @@ "type": "object", "properties": { "fileType": { - "description": "File content kind after the operation (for `delete`, of the deleted file).\n\nOmitted or `null` means the content kind is unknown.", + "description": "File content kind after the operation (for `delete`, of the deleted file).\n\nOmitted and `null` are equivalent and mean the content kind is unknown.", "anyOf": [ { "$ref": "#/$defs/DiffFileType" @@ -1644,7 +1644,7 @@ "x-deserialize-default-on-error": true }, "mimeType": { - "description": "MIME type of the file contents after the operation (for `delete`, of the deleted file).\n\nOmitted or `null` means the MIME type is unknown.", + "description": "MIME type of the file contents after the operation (for `delete`, of the deleted file).\n\nOmitted and `null` are equivalent and mean the MIME type is unknown.", "anyOf": [ { "$ref": "#/$defs/MediaType" @@ -1937,7 +1937,7 @@ "x-deserialize-skip-invalid-items": true }, "patch": { - "description": "Renderable patch text for some or all of the structured changes.\n\nAgents SHOULD provide patch text whenever feasible. Omitted or `null`\nmeans no renderable patch text was provided.", + "description": "Renderable patch text for some or all of the structured changes.\n\nAgents SHOULD provide patch text whenever feasible. Omitted and `null` are\nequivalent and mean no renderable patch text was provided.", "anyOf": [ { "$ref": "#/$defs/DiffPatch" @@ -3278,7 +3278,7 @@ "type": "string" }, "title": { - "description": "Intended for UI and end-user contexts — 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 — optimized to be human-readable\nand easily understood.\n\nIf not provided, the name should be used for display.\n\nOmitted and `null` are equivalent and mean the `name` is used for display.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, @@ -3300,7 +3300,7 @@ "type": "object", "properties": { "session": { - "description": "Session capabilities supported by the agent.\n\nOptional. Omitted or `null` both mean the agent does not support the\n`session/*` method surface. Supplying `{}` means the agent supports the\nbaseline session methods: `session/new`, `session/list`,\n`session/resume`, `session/close`, `session/prompt`, `session/cancel`,\nand `session/update`.", + "description": "Session capabilities supported by the agent.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not support the\n`session/*` method surface. Supplying `{}` means the agent supports the\nbaseline session methods: `session/new`, `session/list`,\n`session/resume`, `session/close`, `session/prompt`, `session/cancel`,\nand `session/update`.", "anyOf": [ { "$ref": "#/$defs/SessionCapabilities" @@ -3312,7 +3312,7 @@ "x-deserialize-default-on-error": true }, "auth": { - "description": "Authentication-related extension capabilities supported by the agent.\n\nOptional. Omitted or `null` both mean the agent does not advertise any\nauthentication-related extensions. This field does not advertise support\nfor `auth/login` or `auth/logout`; those methods are advertised by a\nnon-empty `authMethods` list in the `initialize` response.", + "description": "Authentication-related extension capabilities supported by the agent.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise any\nauthentication-related extensions. This field does not advertise support\nfor `auth/login` or `auth/logout`; those methods are advertised by a\nnon-empty `authMethods` list in the `initialize` response.", "anyOf": [ { "$ref": "#/$defs/AgentAuthCapabilities" @@ -3324,7 +3324,7 @@ "x-deserialize-default-on-error": true }, "providers": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nProvider configuration capabilities supported by the agent.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports provider configuration methods.", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nProvider configuration capabilities supported by the agent.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise support.\nSupplying `{}` means the agent supports provider configuration methods.", "anyOf": [ { "$ref": "#/$defs/ProvidersCapabilities" @@ -3348,7 +3348,7 @@ "type": "object", "properties": { "prompt": { - "description": "Prompt capabilities supported by the agent in `session/prompt` requests.\n\nOptional. Omitted or `null` both mean the agent does not advertise any\nprompt extensions beyond the baseline text and resource-link content\nrequired by `session/prompt`.", + "description": "Prompt capabilities supported by the agent in `session/prompt` requests.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise any\nprompt extensions beyond the baseline text and resource-link content\nrequired by `session/prompt`.", "anyOf": [ { "$ref": "#/$defs/PromptCapabilities" @@ -3360,7 +3360,7 @@ "x-deserialize-default-on-error": true }, "mcp": { - "description": "MCP capabilities supported by the agent for session lifecycle requests.\n\nOptional. Omitted or `null` both mean the agent does not advertise MCP\nserver transport support for sessions.", + "description": "MCP capabilities supported by the agent for session lifecycle requests.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise MCP\nserver transport support for sessions.", "anyOf": [ { "$ref": "#/$defs/McpCapabilities" @@ -3372,7 +3372,7 @@ "x-deserialize-default-on-error": true }, "delete": { - "description": "Whether the agent supports `session/delete`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports deleting sessions from `session/list`.", + "description": "Whether the agent supports `session/delete`.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise support.\nSupplying `{}` means the agent supports deleting sessions from `session/list`.", "anyOf": [ { "$ref": "#/$defs/SessionDeleteCapabilities" @@ -3384,7 +3384,7 @@ "x-deserialize-default-on-error": true }, "additionalDirectories": { - "description": "Whether the agent supports `additionalDirectories` on supported session lifecycle requests.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports `additionalDirectories` on\nsupported session lifecycle requests.\n\nAgents may return `SessionInfo.additionalDirectories` to report the\ncomplete ordered additional-root list associated with a listed session.", + "description": "Whether the agent supports `additionalDirectories` on supported session lifecycle requests.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise support.\nSupplying `{}` means the agent supports `additionalDirectories` on\nsupported session lifecycle requests.\n\nAgents may return `SessionInfo.additionalDirectories` to report the\ncomplete ordered additional-root list associated with a listed session.", "anyOf": [ { "$ref": "#/$defs/SessionAdditionalDirectoriesCapabilities" @@ -3396,7 +3396,7 @@ "x-deserialize-default-on-error": true }, "systemPrompt": { - "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 `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.", + "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 `systemPrompt` on session lifecycle requests.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise support.\nSupplying `{}` means the agent supports `systemPrompt` in `append` mode.", "anyOf": [ { "$ref": "#/$defs/SessionSystemPromptCapabilities" @@ -3408,7 +3408,7 @@ "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.", + "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 and `null` are equivalent and mean the agent does not advertise support.\nSupplying `{}` means the agent supports forking sessions.", "anyOf": [ { "$ref": "#/$defs/SessionForkCapabilities" @@ -3432,7 +3432,7 @@ "type": "object", "properties": { "image": { - "description": "Agent supports `image` content blocks.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports image content in prompts.", + "description": "Agent supports `image` content blocks.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise support.\nSupplying `{}` means the agent supports image content in prompts.", "anyOf": [ { "$ref": "#/$defs/PromptImageCapabilities" @@ -3444,7 +3444,7 @@ "x-deserialize-default-on-error": true }, "audio": { - "description": "Agent supports `audio` content blocks.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports audio content in prompts.", + "description": "Agent supports `audio` content blocks.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise support.\nSupplying `{}` means the agent supports audio content in prompts.", "anyOf": [ { "$ref": "#/$defs/PromptAudioCapabilities" @@ -3456,7 +3456,7 @@ "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 `resource` content blocks\nin prompt requests for pieces of context that are referenced in the message.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports embedded context in prompts.", + "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.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise support.\nSupplying `{}` means the agent supports embedded context in prompts.", "anyOf": [ { "$ref": "#/$defs/PromptEmbeddedContextCapabilities" @@ -3516,7 +3516,7 @@ "type": "object", "properties": { "stdio": { - "description": "Agent supports `stdio` MCP servers.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports stdio MCP server transports.", + "description": "Agent supports `stdio` MCP servers.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise support.\nSupplying `{}` means the agent supports stdio MCP server transports.", "anyOf": [ { "$ref": "#/$defs/McpStdioCapabilities" @@ -3528,7 +3528,7 @@ "x-deserialize-default-on-error": true }, "http": { - "description": "Agent supports `http` MCP servers.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports HTTP MCP server transports.", + "description": "Agent supports `http` MCP servers.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise support.\nSupplying `{}` means the agent supports HTTP MCP server transports.", "anyOf": [ { "$ref": "#/$defs/McpHttpCapabilities" @@ -3540,7 +3540,7 @@ "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 `acp` MCP servers.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports ACP MCP server transports.", + "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.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise support.\nSupplying `{}` means the agent supports ACP MCP server transports.", "anyOf": [ { "$ref": "#/$defs/McpAcpCapabilities" @@ -3624,7 +3624,7 @@ "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`.", + "description": "Delivery modes the agent supports in addition to `append`.\n\nOptional. Omitted and `null` are equivalent and mean the agent supports only `append`.", "anyOf": [ { "$ref": "#/$defs/SessionSystemPromptModeCapabilities" @@ -3648,7 +3648,7 @@ "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.", + "description": "Whether the agent supports `override` mode.\n\nOptional. Omitted and `null` are equivalent and 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" @@ -3843,7 +3843,7 @@ "type": "string" }, "description": { - "description": "Optional description providing more details about this authentication method.", + "description": "Optional description providing more details about this authentication method.\n\nOmitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, @@ -3887,7 +3887,7 @@ "type": "string" }, "description": { - "description": "Optional description providing more details about this authentication method.", + "description": "Optional description providing more details about this authentication method.\n\nOmitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, @@ -4146,12 +4146,12 @@ "type": "string" }, "description": { - "description": "Optional description for the Client to display to the user.", + "description": "Optional description for the Client to display to the user.\n\nOmitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "category": { - "description": "Optional semantic category for this option (UX only).", + "description": "Optional semantic category for this option (UX only).\n\nOmitted and `null` are equivalent and mean no category is provided.", "anyOf": [ { "$ref": "#/$defs/SessionConfigOptionCategory" @@ -4318,7 +4318,7 @@ "type": "string" }, "description": { - "description": "Optional description for this option value.", + "description": "Optional description for this option value.\n\nOmitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, @@ -4537,7 +4537,7 @@ "type": "string" }, "input": { - "description": "Input for the command if required", + "description": "Input for the command if required\n\nOmitted and `null` are equivalent and mean the command takes no input.", "anyOf": [ { "$ref": "#/$defs/AvailableCommandInput" @@ -4623,12 +4623,12 @@ "x-deserialize-skip-invalid-items": true }, "title": { - "description": "Human-readable title for the session", + "description": "Human-readable title for the session\n\nOmitted and `null` are equivalent and mean no title is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "updatedAt": { - "description": "RFC 3339 timestamp of last activity.", + "description": "RFC 3339 timestamp of last activity.\n\nOmitted and `null` are equivalent and mean the last activity time is not reported.", "type": ["string", "null"], "format": "date-time", "x-deserialize-default-on-error": true @@ -4818,7 +4818,7 @@ "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.", + "description": "Optional primitive or structured value that contains additional information about the error.\nThis may include debugging information or context-specific details.\n\nOmitted and `null` are equivalent and mean no additional data is provided.", "x-deserialize-default-on-error": true } }, @@ -5737,7 +5737,7 @@ "type": "object", "properties": { "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.", + "description": "The failure, as a JSON-RPC error object.\n\nOptional. Omitted and `null` are equivalent and mean the agent is not reporting failure details.\nAgents SHOULD include it.", "anyOf": [ { "$ref": "#/$defs/Error" @@ -5773,21 +5773,21 @@ "minimum": 0 }, "thoughtTokens": { - "description": "Total thought/reasoning tokens", + "description": "Total thought/reasoning tokens\n\nOmitted and `null` are equivalent and mean the count is not reported.", "type": ["integer", "null"], "format": "uint64", "minimum": 0, "x-deserialize-default-on-error": true }, "cachedReadTokens": { - "description": "Total cache read tokens.", + "description": "Total cache read tokens.\n\nOmitted and `null` are equivalent and mean the count is not reported.", "type": ["integer", "null"], "format": "uint64", "minimum": 0, "x-deserialize-default-on-error": true }, "cachedWriteTokens": { - "description": "Total cache write tokens.", + "description": "Total cache write tokens.\n\nOmitted and `null` are equivalent and mean the count is not reported.", "type": ["integer", "null"], "format": "uint64", "minimum": 0, @@ -5807,7 +5807,7 @@ "type": "object", "properties": { "usage": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nToken usage for completed foreground work.\n\nOptional. Omitted or `null` both mean the agent is not reporting token\nusage for this state update.", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nToken usage for completed foreground work.\n\nOptional. Omitted and `null` are equivalent and mean the agent is not reporting token\nusage for this state update.", "anyOf": [ { "$ref": "#/$defs/Usage" @@ -5825,7 +5825,7 @@ "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: [Stop Reasons](https://agentclientprotocol.com/protocol/v2/draft/prompt-lifecycle#stop-reasons)", + "description": "Why foreground work stopped. The value selects one of this type's variants, which may add fields of their own.\n\nOptional. Omitted and `null` are equivalent and mean the agent is not reporting a stop reason; a malformed value is treated the same way.\n\nSee protocol docs: [Stop Reasons](https://agentclientprotocol.com/protocol/v2/draft/prompt-lifecycle#stop-reasons)", "type": ["string", "null"], "x-deserialize-default-on-error": true } @@ -6768,7 +6768,7 @@ "minimum": 0 }, "cost": { - "description": "Cumulative session cost (optional).", + "description": "Cumulative session cost (optional).\n\nOmitted and `null` are equivalent and mean no cost is reported.", "anyOf": [ { "$ref": "#/$defs/Cost" @@ -6955,7 +6955,7 @@ "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 and `null` are equivalent and mean unsupported; an object (including\n`{}`) means supported.", "anyOf": [ { "$ref": "#/$defs/SessionCancelCapabilities" @@ -7388,7 +7388,7 @@ "type": "object", "properties": { "auth": { - "description": "Authentication capabilities supported by the client.\nDetermines which authentication method types the agent may include\nin its `InitializeResponse`.\n\nOptional. Omitted or `null` both mean the client does not advertise any\nauthentication-method extensions.", + "description": "Authentication capabilities supported by the client.\nDetermines which authentication method types the agent may include\nin its `InitializeResponse`.\n\nOptional. Omitted and `null` are equivalent and mean the client does not advertise any\nauthentication-method extensions.", "anyOf": [ { "$ref": "#/$defs/ClientAuthCapabilities" @@ -7400,7 +7400,7 @@ "x-deserialize-default-on-error": true }, "elicitation": { - "description": "Elicitation capabilities supported by the client.\nDetermines which elicitation modes the agent may use.\n\nOptional. Omitted or `null` both mean the client does not advertise\nelicitation support.", + "description": "Elicitation capabilities supported by the client.\nDetermines which elicitation modes the agent may use.\n\nOptional. Omitted and `null` are equivalent and mean the client does not advertise\nelicitation support.", "anyOf": [ { "$ref": "#/$defs/ElicitationCapabilities" @@ -7424,7 +7424,7 @@ "type": "object", "properties": { "terminal": { - "description": "Whether the client supports `terminal` authentication methods.\n\nOptional. Omitted or `null` both mean the client does not advertise support.\nThe client should supply `{}` only when it can reproduce the configured\nagent invocation in an interactive terminal. Supplying `{}` means the\nagent may include `terminal` entries in its authentication methods.", + "description": "Whether the client supports `terminal` authentication methods.\n\nOptional. Omitted and `null` are equivalent and mean the client does not advertise support.\nThe client should supply `{}` only when it can reproduce the configured\nagent invocation in an interactive terminal. Supplying `{}` means the\nagent may include `terminal` entries in its authentication methods.", "anyOf": [ { "$ref": "#/$defs/TerminalAuthCapabilities" @@ -7472,7 +7472,7 @@ "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.", + "description": "Whether the client supports URL-based elicitation.\n\nOptional. Omitted and `null` are equivalent and mean the client does not advertise support.\nSupplying `{}` means the client supports URL-based elicitation.", "anyOf": [ { "$ref": "#/$defs/ElicitationUrlCapabilities" @@ -7947,7 +7947,7 @@ "type": "object", "properties": { "cwd": { - "description": "Filter sessions by working directory. Must be an absolute path.", + "description": "Filter sessions by working directory. Must be an absolute path.\n\nOmitted and `null` are equivalent and mean sessions are not filtered by working directory.", "anyOf": [ { "$ref": "#/$defs/AbsolutePath" @@ -7958,7 +7958,7 @@ ] }, "cursor": { - "description": "Opaque cursor token from a previous response's nextCursor field for cursor-based pagination", + "description": "Opaque cursor token from a previous response's nextCursor field for cursor-based pagination\n\nOmitted and `null` are equivalent and mean the first page is requested.", "anyOf": [ { "$ref": "#/$defs/SessionListCursor" @@ -8092,7 +8092,7 @@ } }, "replayFrom": { - "description": "Inclusive cursor describing where conversation replay should begin.\n\nOptional. Omitted or `null` both mean the Agent should resume without\nreplaying previous conversation history. Replay cursors are inclusive:\nreplay includes the position identified by the cursor. Supplying\n`{ \"type\": \"start\" }` means the Agent should replay all retained\nconversation history before responding.\n\nAgents MUST reject unsupported cursor types or malformed cursor values\nwith `-32602` (Invalid params), rather than substituting another cursor\nor resuming without replay.", + "description": "Inclusive cursor describing where conversation replay should begin.\n\nOptional. Omitted and `null` are equivalent and mean the Agent should resume without\nreplaying previous conversation history. Replay cursors are inclusive:\nreplay includes the position identified by the cursor. Supplying\n`{ \"type\": \"start\" }` means the Agent should replay all retained\nconversation history before responding.\n\nAgents MUST reject unsupported cursor types or malformed cursor values\nwith `-32602` (Invalid params), rather than substituting another cursor\nor resuming without replay.", "anyOf": [ { "$ref": "#/$defs/ReplayFrom" @@ -8710,7 +8710,7 @@ "type": "object", "properties": { "content": { - "description": "The user-provided content, if any, as an object matching the requested schema.", + "description": "The user-provided content, if any, as an object matching the requested schema.\n\nOmitted and `null` are equivalent and mean no content is provided.", "type": ["object", "null"], "additionalProperties": { "$ref": "#/$defs/ElicitationContentValue"