From a77f5c636ccc5df4868d0ee9b5a96ba4ba21ebc1 Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Thu, 20 Aug 2026 13:16:02 -0700 Subject: [PATCH] feat: Stabilize elicitation APIs Updates schema to 1.21.0 --- schema/schema.json | 394 ++++++++++++++++++------------- schema/v2/schema.unstable.json | 415 ++++++++++++++++++-------------- scripts/generate.js | 4 +- src/acp.test.ts | 24 +- src/acp.ts | 67 ++---- src/schema/guards.gen.ts | 16 -- src/schema/index.ts | 7 +- src/schema/types.gen.ts | 416 ++++++++++++++++++--------------- src/schema/zod.gen.ts | 251 +++++++++----------- src/v2/acp.ts | 11 +- src/v2/schema/guards.gen.ts | 62 ++--- src/v2/schema/index.ts | 6 +- src/v2/schema/types.gen.ts | 402 +++++++++++++++---------------- src/v2/schema/zod.gen.ts | 253 ++++++++------------ 14 files changed, 1186 insertions(+), 1142 deletions(-) diff --git a/schema/schema.json b/schema/schema.json index a23ff3f6..534a840a 100644 --- a/schema/schema.json +++ b/schema/schema.json @@ -215,7 +215,7 @@ }, { "title": "CreateElicitationRequest", - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequests structured user input via a form or URL.", + "description": "Requests structured user input via a form or URL.\n\nSee protocol docs: [Elicitation](https://agentclientprotocol.com/protocol/elicitation)", "allOf": [ { "$ref": "#/$defs/CreateElicitationRequest" @@ -1383,7 +1383,7 @@ "x-method": "terminal/kill" }, "CreateElicitationRequest": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest from the agent to elicit structured user input.\n\nThe agent sends this to the client to request information from the user,\neither via a form or by directing them to a URL.\nElicitations are tied to a session (optionally a tool call) or a request.", + "description": "Request from the agent to elicit structured user input.\n\nThe agent sends this to the client to request information from the user,\neither via a form or by directing them to a URL.\nElicitations are tied to a session (optionally a tool call) or a request.", "type": "object", "properties": { "message": { @@ -1391,7 +1391,7 @@ "type": "string" }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -1493,7 +1493,7 @@ "x-method": "elicitation/create" }, "ElicitationSessionScope": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSession-scoped elicitation, optionally tied to a specific tool call.\n\nWhen `tool_call_id` is set, the elicitation is tied to a specific tool call.\nThis is useful when an agent receives an elicitation from an MCP server\nduring a tool call and needs to redirect it to the user.", + "description": "Session-scoped elicitation, optionally tied to a specific tool call.\n\nWhen `tool_call_id` is set, the elicitation is tied to a specific tool call.\nThis is useful when an agent receives an elicitation from an MCP server\nduring a tool call and needs to redirect it to the user.", "type": "object", "properties": { "sessionId": { @@ -1505,7 +1505,7 @@ ] }, "toolCallId": { - "description": "Optional tool call within the session.", + "description": "Optional tool call within the session.\n\nOptional. Omitted and `null` are equivalent and mean the elicitation is scoped to the\nsession without a specific tool call.", "anyOf": [ { "$ref": "#/$defs/ToolCallId" @@ -1520,7 +1520,7 @@ "required": ["sessionId"] }, "ElicitationRequestScope": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest-scoped elicitation, tied to a specific JSON-RPC request outside of a session\n(e.g., during auth/configuration phases before any session is started).", + "description": "Request-scoped elicitation, tied to a specific JSON-RPC request outside of a session\n(e.g., during auth/configuration phases before any session is started).", "type": "object", "properties": { "requestId": { @@ -1549,7 +1549,7 @@ ] }, "title": { - "description": "Optional title for the schema.", + "description": "Optional title for the schema.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, @@ -1562,19 +1562,19 @@ } }, "required": { - "description": "List of required property names.", + "description": "List of required property names.\n\nOptional. Omitted and `null` are equivalent and mean no property names are required.", "type": ["array", "null"], "items": { "type": "string" } }, "description": { - "description": "Optional description of what this schema represents.", + "description": "Optional description of what this schema represents.\n\nOptional. Omitted and `null` are equivalent and mean no schema description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -1781,12 +1781,12 @@ "type": "string" }, "description": { - "description": "Human-readable description.", + "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -1799,33 +1799,33 @@ "type": "object", "properties": { "title": { - "description": "Optional title for the property.", + "description": "Optional title for the property.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "description": { - "description": "Human-readable description.", + "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "minLength": { - "description": "Minimum string length.", + "description": "Minimum string length.\n\nOptional. Omitted and `null` are equivalent and mean there is no minimum length constraint.", "type": ["integer", "null"], "format": "uint32", "minimum": 0 }, "maxLength": { - "description": "Maximum string length.", + "description": "Maximum string length.\n\nOptional. Omitted and `null` are equivalent and mean there is no maximum length constraint.", "type": ["integer", "null"], "format": "uint32", "minimum": 0 }, "pattern": { - "description": "Pattern the string must match.", + "description": "Pattern the string must match.\n\nOptional. Omitted and `null` are equivalent and mean there is no pattern constraint.", "type": ["string", "null"] }, "format": { - "description": "String format.", + "description": "String format.\n\nOptional. Omitted and `null` are equivalent and mean there is no format constraint.", "anyOf": [ { "$ref": "#/$defs/StringFormat" @@ -1836,26 +1836,26 @@ ] }, "default": { - "description": "Default value.", + "description": "Default value.\n\nOptional. Omitted and `null` are equivalent and mean no default value is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "enum": { - "description": "Enum values for untitled single-select enums.", + "description": "Enum values for untitled single-select enums.\nOptional. Omitted and `null` are equivalent and mean no untitled single-select choices are\ndeclared by `enum`.", "type": ["array", "null"], "items": { "type": "string" } }, "oneOf": { - "description": "Titled enum options for titled single-select enums.", + "description": "Titled enum options for titled single-select enums.\nOptional. Omitted and `null` are equivalent and mean no titled single-select choices are\ndeclared by `oneOf`.", "type": ["array", "null"], "items": { "$ref": "#/$defs/EnumOption" } }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -1867,33 +1867,33 @@ "type": "object", "properties": { "title": { - "description": "Optional title for the property.", + "description": "Optional title for the property.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "description": { - "description": "Human-readable description.", + "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "minimum": { - "description": "Minimum value (inclusive).", + "description": "Minimum value (inclusive).\n\nOptional. Omitted and `null` are equivalent and mean there is no inclusive lower bound.", "type": ["number", "null"], "format": "double" }, "maximum": { - "description": "Maximum value (inclusive).", + "description": "Maximum value (inclusive).\n\nOptional. Omitted and `null` are equivalent and mean there is no inclusive upper bound.", "type": ["number", "null"], "format": "double" }, "default": { - "description": "Default value.", + "description": "Default value.\n\nOptional. Omitted and `null` are equivalent and mean no default value is provided.", "type": ["number", "null"], "format": "double", "x-deserialize-default-on-error": true }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -1905,33 +1905,33 @@ "type": "object", "properties": { "title": { - "description": "Optional title for the property.", + "description": "Optional title for the property.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "description": { - "description": "Human-readable description.", + "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "minimum": { - "description": "Minimum value (inclusive).", + "description": "Minimum value (inclusive).\n\nOptional. Omitted and `null` are equivalent and mean there is no inclusive lower bound.", "type": ["integer", "null"], "format": "int64" }, "maximum": { - "description": "Maximum value (inclusive).", + "description": "Maximum value (inclusive).\n\nOptional. Omitted and `null` are equivalent and mean there is no inclusive upper bound.", "type": ["integer", "null"], "format": "int64" }, "default": { - "description": "Default value.", + "description": "Default value.\n\nOptional. Omitted and `null` are equivalent and mean no default value is provided.", "type": ["integer", "null"], "format": "int64", "x-deserialize-default-on-error": true }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -1943,22 +1943,22 @@ "type": "object", "properties": { "title": { - "description": "Optional title for the property.", + "description": "Optional title for the property.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "description": { - "description": "Human-readable description.", + "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "default": { - "description": "Default value.", + "description": "Default value.\n\nOptional. Omitted and `null` are equivalent and mean no default value is provided.", "type": ["boolean", "null"], "x-deserialize-default-on-error": true }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -2034,7 +2034,7 @@ } }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -2054,7 +2054,7 @@ } }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -2067,23 +2067,23 @@ "type": "object", "properties": { "title": { - "description": "Optional title for the property.", + "description": "Optional title for the property.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "description": { - "description": "Human-readable description.", + "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "minItems": { - "description": "Minimum number of items to select.", + "description": "Minimum number of items to select.\n\nOptional. Omitted and `null` are equivalent and mean there is no minimum selection count.", "type": ["integer", "null"], "format": "uint64", "minimum": 0 }, "maxItems": { - "description": "Maximum number of items to select.", + "description": "Maximum number of items to select.\n\nOptional. Omitted and `null` are equivalent and mean there is no maximum selection count.", "type": ["integer", "null"], "format": "uint64", "minimum": 0 @@ -2097,7 +2097,7 @@ ] }, "default": { - "description": "Default selected values.", + "description": "Default selected values.\n\nOptional. Omitted and `null` are equivalent and mean no default selections are provided.", "type": ["array", "null"], "items": { "type": "string" @@ -2106,7 +2106,7 @@ "x-deserialize-skip-invalid-items": true }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -2115,7 +2115,7 @@ "required": ["items"] }, "ElicitationFormMode": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nForm-based elicitation mode where the client renders a form from the provided schema.", + "description": "Form-based elicitation mode where the client renders a form from the provided schema.", "type": "object", "properties": { "requestedSchema": { @@ -2150,11 +2150,11 @@ "required": ["requestedSchema"] }, "ElicitationId": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnique identifier for an elicitation.", + "description": "Unique identifier for an elicitation.", "type": "string" }, "ElicitationUrlMode": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nURL-based elicitation mode where the client directs the user to a URL.", + "description": "URL-based elicitation mode where the client directs the user to a URL.", "type": "object", "properties": { "elicitationId": { @@ -3381,23 +3381,7 @@ "description": "Describes an available authentication method.\n\nThe `type` field acts as the discriminator in the serialized JSON form.\nWhen no `type` is present, the method is treated as `agent`.", "anyOf": [ { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUser provides a key that the client passes to the agent as an environment variable.", - "type": "object", - "properties": { - "type": { - "type": "string", - "const": "env_var" - } - }, - "required": ["type"], - "allOf": [ - { - "$ref": "#/$defs/AuthMethodEnvVar" - } - ] - }, - { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nClient runs an interactive terminal for the user to authenticate via a TUI.", + "description": "Client runs the configured agent program as a separate interactive\nprocess, without passing this method to `authenticate`.", "type": "object", "properties": { "type": { @@ -3414,7 +3398,7 @@ }, { "title": "agent", - "description": "Agent handles authentication itself.\n\nThis is the default when no `type` is specified.", + "description": "Agent handles authentication itself through `authenticate`.\n\nThis is the default when no `type` is specified.", "allOf": [ { "$ref": "#/$defs/AuthMethodAgent" @@ -3427,86 +3411,8 @@ "description": "Typed identifier used for auth method values on the wire.", "type": "string" }, - "AuthEnvVar": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nDescribes a single environment variable for an [`AuthMethodEnvVar`] authentication method.", - "type": "object", - "properties": { - "name": { - "description": "The environment variable name (e.g. `\"OPENAI_API_KEY\"`).", - "type": "string" - }, - "label": { - "description": "Human-readable label for this variable, displayed in client UI.", - "type": ["string", "null"], - "x-deserialize-default-on-error": true - }, - "secret": { - "description": "Whether this value is a secret (e.g. API key, token).\nClients should use a password-style input for secret vars.\n\nDefaults to `true`.", - "type": "boolean", - "x-deserialize-default-on-error": true, - "default": true - }, - "optional": { - "description": "Whether this variable is optional.\n\nDefaults to `false`.", - "type": "boolean", - "x-deserialize-default-on-error": true, - "default": false - }, - "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", - "type": ["object", "null"], - "x-deserialize-default-on-error": true, - "additionalProperties": true - } - }, - "required": ["name"] - }, - "AuthMethodEnvVar": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nEnvironment variable authentication method.\n\nThe user provides credentials that the client passes to the agent as environment variables.", - "type": "object", - "properties": { - "id": { - "description": "Unique identifier for this authentication method.", - "allOf": [ - { - "$ref": "#/$defs/AuthMethodId" - } - ] - }, - "name": { - "description": "Human-readable name of the authentication method.", - "type": "string" - }, - "description": { - "description": "Optional description providing more details about this authentication method.", - "type": ["string", "null"], - "x-deserialize-default-on-error": true - }, - "vars": { - "description": "The environment variables the client should set.", - "type": "array", - "items": { - "$ref": "#/$defs/AuthEnvVar" - }, - "x-deserialize-default-on-error": true, - "x-deserialize-skip-invalid-items": true - }, - "link": { - "description": "Optional link to a page where the user can obtain their credentials.", - "type": ["string", "null"], - "x-deserialize-default-on-error": true - }, - "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", - "type": ["object", "null"], - "x-deserialize-default-on-error": true, - "additionalProperties": true - } - }, - "required": ["id", "name", "vars"] - }, "AuthMethodTerminal": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nTerminal-based authentication method.\n\nThe client runs an interactive terminal for the user to authenticate via a TUI.", + "description": "Terminal-based authentication method.\n\nThe client runs the configured agent program as a separate interactive\nprocess for the user to authenticate via a TUI. Agents MUST advertise this\nmethod only when the client enabled its terminal authentication capability.\nA zero exit status signals success; any other termination signals failure.\nThe client MUST NOT pass this method to `authenticate`.", "type": "object", "properties": { "id": { @@ -3527,7 +3433,7 @@ "x-deserialize-default-on-error": true }, "args": { - "description": "Additional arguments to pass when running the agent binary for terminal auth.", + "description": "Additional arguments to append to the configured agent invocation for terminal auth.", "type": "array", "items": { "type": "string" @@ -3536,7 +3442,7 @@ "x-deserialize-skip-invalid-items": true }, "env": { - "description": "Additional environment variables to set when running the agent binary for terminal auth.", + "description": "Additional environment variables to set on the configured agent invocation for terminal auth.\nThese values override same-named variables in the base launch configuration.", "type": "object", "x-deserialize-default-on-error": true, "additionalProperties": { @@ -3553,7 +3459,7 @@ "required": ["id", "name"] }, "AuthMethodAgent": { - "description": "Agent handles authentication itself.\n\nThis is the default authentication method type.", + "description": "Agent handles authentication itself through `authenticate`.\n\nThis is the default authentication method type.", "type": "object", "properties": { "id": { @@ -5001,7 +4907,7 @@ }, { "title": "CompleteElicitationNotification", - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nNotification that a URL-based elicitation has completed.", + "description": "Notification that a URL-based elicitation has completed.\n\nSee protocol docs: [Elicitation](https://agentclientprotocol.com/protocol/elicitation#url-completion)", "allOf": [ { "$ref": "#/$defs/CompleteElicitationNotification" @@ -5278,6 +5184,38 @@ "$ref": "#/$defs/UsageUpdate" } ] + }, + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA context compaction has been created or updated.\n\nAgents MUST only send this update when the Client advertised\n[`ClientSessionCapabilities::compaction`].", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "compaction_update" + } + }, + "required": ["sessionUpdate"], + "allOf": [ + { + "$ref": "#/$defs/CompactionUpdate" + } + ] + }, + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA content block appended to a context compaction's retained summary.\n\nAgents MUST only send this update when the Client advertised\n[`ClientSessionCapabilities::compaction`].", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "compaction_summary_chunk" + } + }, + "required": ["sessionUpdate"], + "allOf": [ + { + "$ref": "#/$defs/CompactionSummaryChunk" + } + ] } ], "discriminator": { @@ -5882,8 +5820,114 @@ }, "required": ["used", "size"] }, + "CompactionId": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnique identifier for a context compaction within a session.", + "type": "string" + }, + "CompactionStatus": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nLifecycle state of a context compaction.", + "anyOf": [ + { + "description": "Compaction has started and has not finished.", + "type": "string", + "const": "in_progress" + }, + { + "description": "Compaction finished successfully.", + "type": "string", + "const": "completed" + }, + { + "description": "Compaction finished unsuccessfully.", + "type": "string", + "const": "failed" + }, + { + "description": "Compaction was cancelled before it finished.", + "type": "string", + "const": "cancelled" + }, + { + "title": "other", + "description": "Custom or future compaction status.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Other unknown values are reserved for future ACP statuses.", + "type": "string" + } + ] + }, + "CompactionUpdate": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA context compaction upsert. The first update fixes the compaction's\ntimeline position. Later updates with the same ID patch that entity in place.\nAgents MUST only send this update when the Client advertised\n[`ClientSessionCapabilities::compaction`].\n\n`summary`, `error`, and `_meta` have patch semantics: omission leaves the\nstored value unchanged, `null` clears it, and a concrete value replaces it.\n`summary: []` also clears the retained summary. A non-empty summary is only\nvalid with `completed`; `error` is only valid with `failed`.", + "type": "object", + "properties": { + "compactionId": { + "description": "The Agent-owned ID of this compaction, unique within the session.", + "allOf": [ + { + "$ref": "#/$defs/CompactionId" + } + ] + }, + "status": { + "description": "Current lifecycle status.", + "allOf": [ + { + "$ref": "#/$defs/CompactionStatus" + } + ] + }, + "summary": { + "description": "Complete replacement user-displayable summary retained by the compaction.", + "type": ["array", "null"], + "items": { + "$ref": "#/$defs/ContentBlock" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "error": { + "description": "Human-readable description of why the compaction failed.", + "type": ["string", "null"], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "Extensible metadata patch for this compaction.", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": ["compactionId", "status"] + }, + "CompactionSummaryChunk": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA content block appended to the retained summary of an in-progress\ncompaction. Agents send chunks only after an `in_progress` update and before\nthe terminal update for the same ID. Agents MUST only send this update when\nthe Client advertised [`ClientSessionCapabilities::compaction`].", + "type": "object", + "properties": { + "compactionId": { + "description": "ID of the compaction whose summary receives this content.", + "allOf": [ + { + "$ref": "#/$defs/CompactionId" + } + ] + }, + "content": { + "description": "One content block to append.", + "allOf": [ + { + "$ref": "#/$defs/ContentBlock" + } + ] + }, + "_meta": { + "description": "Metadata scoped to this chunk. Omission and `null` both mean absent.", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": ["compactionId", "content"] + }, "CompleteElicitationNotification": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nNotification sent by the agent when a URL-based elicitation is complete.", + "description": "Notification sent by the agent when a URL-based elicitation is complete.", "type": "object", "properties": { "elicitationId": { @@ -5895,7 +5939,7 @@ ] }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -5974,7 +6018,7 @@ }, { "title": "AuthenticateRequest", - "description": "Authenticates the client using the specified authentication method.\n\nCalled when the agent requires authentication before allowing session creation.\nThe client provides the authentication method ID that was advertised during initialization.\n\nAfter successful authentication, the client can proceed to create sessions with\n`new_session` without receiving an `auth_required` error.\n\nSee protocol docs: [Initialization](https://agentclientprotocol.com/protocol/initialization)", + "description": "Authenticates the client using the specified authentication method.\n\nCalled when the agent requires authentication before allowing session creation.\nThe client provides an authentication method ID that was advertised during\ninitialization and whose type defines the `authenticate` flow.\n\nAfter successful authentication, the client can proceed to create sessions with\n`new_session` without receiving an `auth_required` error.\n\nSee protocol docs: [Initialization](https://agentclientprotocol.com/protocol/initialization)", "allOf": [ { "$ref": "#/$defs/AuthenticateRequest" @@ -6265,7 +6309,7 @@ "x-deserialize-default-on-error": true }, "auth": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAuthentication capabilities supported by the client.\nDetermines which authentication method types the agent may include\nin its `InitializeResponse`.", + "description": "Authentication capabilities supported by the client.\nDetermines which authentication method types the agent may include\nin its `InitializeResponse`.", "x-deserialize-default-on-error": true, "default": { "terminal": false @@ -6277,7 +6321,7 @@ ] }, "elicitation": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nElicitation 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 or `null` both mean the client does not advertise\nelicitation support.", "anyOf": [ { "$ref": "#/$defs/ElicitationCapabilities" @@ -6345,6 +6389,18 @@ "description": "Session-related capabilities supported by the client.", "type": "object", "properties": { + "compaction": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSupport for ID-addressed context compaction updates. Omitted or `null`\nmeans unsupported; `{}` advertises the complete compaction contract.", + "anyOf": [ + { + "$ref": "#/$defs/CompactionCapabilities" + }, + { + "type": "null" + } + ], + "x-deserialize-default-on-error": true + }, "configOptions": { "description": "Config option capabilities supported by the client.\n\nOmitted or `null` both mean the client does not advertise support for any\nconfig option extensions.", "anyOf": [ @@ -6365,6 +6421,10 @@ } } }, + "CompactionCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nClient support for ID-addressed context compaction updates.", + "type": "object" + }, "SessionConfigOptionsCapabilities": { "description": "Session configuration option capabilities supported by the client.", "type": "object", @@ -6414,11 +6474,11 @@ } }, "AuthCapabilities": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAuthentication capabilities supported by the client.\n\nAdvertised during initialization to inform the agent which authentication\nmethod types the client can handle. This governs opt-in types that require\nadditional client-side support.", + "description": "Authentication capabilities supported by the client.\n\nAdvertised during initialization to inform the agent which authentication\nmethod types the client can handle. This governs opt-in types that require\nadditional client-side support.", "type": "object", "properties": { "terminal": { - "description": "Whether the client supports `terminal` authentication methods.\n\nWhen `true`, the agent may include `terminal` entries in its authentication methods.", + "description": "Whether the client supports `terminal` authentication methods.\n\nThe client should set this to `true` only when it can reproduce the\nconfigured agent invocation in an interactive terminal. When `true`, the\nagent may include `terminal` entries in its authentication methods.", "type": "boolean", "default": false, "x-deserialize-default-on-error": true @@ -6432,11 +6492,11 @@ } }, "ElicitationCapabilities": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nElicitation capabilities supported by the client.", + "description": "Elicitation capabilities supported by the client.", "type": "object", "properties": { "form": { - "description": "Whether the client supports form-based elicitation.\n\nOptional. Omitted or `null` both mean the client does not advertise support.\nSupplying `{}` means the client supports form-based elicitation.", + "description": "Whether the client supports form-based elicitation.\n\nOptional. Omitted and `null` are equivalent and mean form support is not advertised.\nSupplying `{}` explicitly advertises form support.", "anyOf": [ { "$ref": "#/$defs/ElicitationFormCapabilities" @@ -6460,7 +6520,7 @@ "x-deserialize-default-on-error": true }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -6468,11 +6528,11 @@ } }, "ElicitationFormCapabilities": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nForm-based elicitation capabilities.\n\nSupplying `{}` means the client supports form-based elicitation.", + "description": "Form-based elicitation capabilities.\n\nSupplying `{}` means the client supports form-based elicitation.", "type": "object", "properties": { "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -6480,11 +6540,11 @@ } }, "ElicitationUrlCapabilities": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nURL-based elicitation capabilities.\n\nSupplying `{}` means the client supports URL-based elicitation.", + "description": "URL-based elicitation capabilities.\n\nSupplying `{}` means the client supports URL-based elicitation.", "type": "object", "properties": { "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -8159,11 +8219,11 @@ "x-method": "terminal/kill" }, "CreateElicitationResponse": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse from the client to an elicitation request.", + "description": "Response from the client to an elicitation request.", "type": "object", "properties": { "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -8295,7 +8355,7 @@ ] }, "ElicitationAcceptAction": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe user accepted the elicitation and provided content.", + "description": "The user accepted the elicitation and provided content.", "type": "object", "properties": { "content": { diff --git a/schema/v2/schema.unstable.json b/schema/v2/schema.unstable.json index 09d2a0ad..b208c4d1 100644 --- a/schema/v2/schema.unstable.json +++ b/schema/v2/schema.unstable.json @@ -593,7 +593,7 @@ }, { "title": "CreateElicitationRequest", - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequests structured user input via a form or URL.", + "description": "Requests structured user input via a form or URL.\n\nSee protocol docs: [Elicitation](https://agentclientprotocol.com/protocol/v2/draft/elicitation)", "allOf": [ { "$ref": "#/$defs/CreateElicitationRequest" @@ -2190,7 +2190,7 @@ ] }, "CreateElicitationRequest": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest from the agent to elicit structured user input.\n\nThe agent sends this to the client to request information from the user,\neither via a form or by directing them to a URL.\nElicitations are tied to a session (optionally a tool call) or a request.", + "description": "Request from the agent to elicit structured user input.\n\nThe agent sends this to the client to request information from the user,\neither via a form or by directing them to a URL.\nElicitations are tied to a session (optionally a tool call) or a request.", "type": "object", "properties": { "message": { @@ -2198,7 +2198,7 @@ "type": "string" }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -2300,7 +2300,7 @@ "x-method": "elicitation/create" }, "ElicitationSessionScope": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSession-scoped elicitation, optionally tied to a specific tool call.\n\nWhen `tool_call_id` is set, the elicitation is tied to a specific tool call.\nThis is useful when an agent receives an elicitation from an MCP server\nduring a tool call and needs to redirect it to the user.", + "description": "Session-scoped elicitation, optionally tied to a specific tool call.\n\nWhen `tool_call_id` is set, the elicitation is tied to a specific tool call.\nThis is useful when an agent receives an elicitation from an MCP server\nduring a tool call and needs to redirect it to the user.", "type": "object", "properties": { "sessionId": { @@ -2312,7 +2312,7 @@ ] }, "toolCallId": { - "description": "Optional tool call within the session.", + "description": "Optional tool call within the session.\n\nOptional. Omitted and `null` are equivalent and mean the elicitation is scoped to the\nsession without a specific tool call.", "anyOf": [ { "$ref": "#/$defs/ToolCallId" @@ -2327,7 +2327,7 @@ "required": ["sessionId"] }, "ElicitationRequestScope": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest-scoped elicitation, tied to a specific JSON-RPC request outside of a session\n(e.g., during auth/configuration phases before any session is started).", + "description": "Request-scoped elicitation, tied to a specific JSON-RPC request outside of a session\n(e.g., during auth/configuration phases before any session is started).", "type": "object", "properties": { "requestId": { @@ -2356,7 +2356,7 @@ ] }, "title": { - "description": "Optional title for the schema.", + "description": "Optional title for the schema.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, @@ -2369,19 +2369,19 @@ } }, "required": { - "description": "List of required property names.", + "description": "List of required property names.\n\nOptional. Omitted and `null` are equivalent and mean no property names are required.", "type": ["array", "null"], "items": { "type": "string" } }, "description": { - "description": "Optional description of what this schema represents.", + "description": "Optional description of what this schema represents.\n\nOptional. Omitted and `null` are equivalent and mean no schema description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -2593,12 +2593,12 @@ "type": "string" }, "description": { - "description": "Human-readable description.", + "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -2611,34 +2611,34 @@ "type": "object", "properties": { "title": { - "description": "Optional title for the property.", + "description": "Optional title for the property.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "description": { - "description": "Human-readable description.", + "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "minLength": { - "description": "Minimum string length.", + "description": "Minimum string length.\n\nOptional. Omitted and `null` are equivalent and mean there is no minimum length constraint.", "type": ["integer", "null"], "format": "uint32", "minimum": 0 }, "maxLength": { - "description": "Maximum string length.", + "description": "Maximum string length.\n\nOptional. Omitted and `null` are equivalent and mean there is no maximum length constraint.", "type": ["integer", "null"], "format": "uint32", "minimum": 0 }, "pattern": { - "description": "Pattern the string must match.", + "description": "Pattern the string must match.\n\nOptional. Omitted and `null` are equivalent and mean there is no pattern constraint.", "type": ["string", "null"], "format": "regex" }, "format": { - "description": "String format.", + "description": "String format.\n\nOptional. Omitted and `null` are equivalent and mean there is no format constraint.", "anyOf": [ { "$ref": "#/$defs/StringFormat" @@ -2649,12 +2649,12 @@ ] }, "default": { - "description": "Default value.", + "description": "Default value.\n\nOptional. Omitted and `null` are equivalent and mean no default value is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "enum": { - "description": "Enum values for untitled single-select enums.\nMust contain at least one value when present.", + "description": "Enum values for untitled single-select enums.\nMust contain at least one value when present.\nOptional. Omitted and `null` are equivalent and mean no untitled single-select choices are\ndeclared by `enum`.", "type": ["array", "null"], "items": { "type": "string" @@ -2662,7 +2662,7 @@ "minItems": 1 }, "oneOf": { - "description": "Titled enum options for titled single-select enums.\nMust contain at least one option when present.", + "description": "Titled enum options for titled single-select enums.\nMust contain at least one option when present.\nOptional. Omitted and `null` are equivalent and mean no titled single-select choices are\ndeclared by `oneOf`.", "type": ["array", "null"], "items": { "$ref": "#/$defs/EnumOption" @@ -2670,7 +2670,7 @@ "minItems": 1 }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -2682,33 +2682,33 @@ "type": "object", "properties": { "title": { - "description": "Optional title for the property.", + "description": "Optional title for the property.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "description": { - "description": "Human-readable description.", + "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "minimum": { - "description": "Minimum value (inclusive).", + "description": "Minimum value (inclusive).\n\nOptional. Omitted and `null` are equivalent and mean there is no inclusive lower bound.", "type": ["number", "null"], "format": "double" }, "maximum": { - "description": "Maximum value (inclusive).", + "description": "Maximum value (inclusive).\n\nOptional. Omitted and `null` are equivalent and mean there is no inclusive upper bound.", "type": ["number", "null"], "format": "double" }, "default": { - "description": "Default value.", + "description": "Default value.\n\nOptional. Omitted and `null` are equivalent and mean no default value is provided.", "type": ["number", "null"], "format": "double", "x-deserialize-default-on-error": true }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -2720,33 +2720,33 @@ "type": "object", "properties": { "title": { - "description": "Optional title for the property.", + "description": "Optional title for the property.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "description": { - "description": "Human-readable description.", + "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "minimum": { - "description": "Minimum value (inclusive).", + "description": "Minimum value (inclusive).\n\nOptional. Omitted and `null` are equivalent and mean there is no inclusive lower bound.", "type": ["integer", "null"], "format": "int64" }, "maximum": { - "description": "Maximum value (inclusive).", + "description": "Maximum value (inclusive).\n\nOptional. Omitted and `null` are equivalent and mean there is no inclusive upper bound.", "type": ["integer", "null"], "format": "int64" }, "default": { - "description": "Default value.", + "description": "Default value.\n\nOptional. Omitted and `null` are equivalent and mean no default value is provided.", "type": ["integer", "null"], "format": "int64", "x-deserialize-default-on-error": true }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -2758,22 +2758,22 @@ "type": "object", "properties": { "title": { - "description": "Optional title for the property.", + "description": "Optional title for the property.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "description": { - "description": "Human-readable description.", + "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "default": { - "description": "Default value.", + "description": "Default value.\n\nOptional. Omitted and `null` are equivalent and mean no default value is provided.", "type": ["boolean", "null"], "x-deserialize-default-on-error": true }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -2850,7 +2850,7 @@ "minItems": 1 }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -2871,7 +2871,7 @@ "minItems": 1 }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -2884,23 +2884,23 @@ "type": "object", "properties": { "title": { - "description": "Optional title for the property.", + "description": "Optional title for the property.\n\nOptional. Omitted and `null` are equivalent and mean no title is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "description": { - "description": "Human-readable description.", + "description": "Human-readable description.\n\nOptional. Omitted and `null` are equivalent and mean no description is provided.", "type": ["string", "null"], "x-deserialize-default-on-error": true }, "minItems": { - "description": "Minimum number of items to select.", + "description": "Minimum number of items to select.\n\nOptional. Omitted and `null` are equivalent and mean there is no minimum selection count.", "type": ["integer", "null"], "format": "uint64", "minimum": 0 }, "maxItems": { - "description": "Maximum number of items to select.", + "description": "Maximum number of items to select.\n\nOptional. Omitted and `null` are equivalent and mean there is no maximum selection count.", "type": ["integer", "null"], "format": "uint64", "minimum": 0 @@ -2914,7 +2914,7 @@ ] }, "default": { - "description": "Default selected values.", + "description": "Default selected values.\n\nOptional. Omitted and `null` are equivalent and mean no default selections are provided.", "type": ["array", "null"], "items": { "type": "string" @@ -2923,7 +2923,7 @@ "x-deserialize-skip-invalid-items": true }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -2932,7 +2932,7 @@ "required": ["items"] }, "ElicitationFormMode": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nForm-based elicitation mode where the client renders a form from the provided schema.", + "description": "Form-based elicitation mode where the client renders a form from the provided schema.", "type": "object", "properties": { "requestedSchema": { @@ -2967,11 +2967,11 @@ "required": ["requestedSchema"] }, "ElicitationId": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnique identifier for an elicitation.", + "description": "Unique identifier for an elicitation.", "type": "string" }, "ElicitationUrlMode": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nURL-based elicitation mode where the client directs the user to a URL.", + "description": "URL-based elicitation mode where the client directs the user to a URL.", "type": "object", "properties": { "elicitationId": { @@ -4193,23 +4193,7 @@ "description": "Describes an available authentication method.\n\nThe `type` field acts as the discriminator in the serialized JSON form.", "anyOf": [ { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUser provides a key that the client passes to the agent as an environment variable.", - "type": "object", - "properties": { - "type": { - "type": "string", - "const": "env_var" - } - }, - "required": ["type"], - "allOf": [ - { - "$ref": "#/$defs/AuthMethodEnvVar" - } - ] - }, - { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nClient runs an interactive terminal for the user to authenticate via a TUI.", + "description": "Client runs the configured agent program as a separate interactive\nprocess, without passing this method to `auth/login`.", "type": "object", "properties": { "type": { @@ -4225,7 +4209,7 @@ ] }, { - "description": "Agent handles authentication itself.\n\nThe `type` discriminator value is `agent`.", + "description": "Agent handles authentication itself through `auth/login`.\n\nThe `type` discriminator value is `agent`.", "type": "object", "properties": { "type": { @@ -4286,16 +4270,6 @@ }, "required": ["type"] }, - { - "type": "object", - "properties": { - "type": { - "type": "string", - "const": "env_var" - } - }, - "required": ["type"] - }, { "type": "object", "properties": { @@ -4316,87 +4290,8 @@ "description": "Typed identifier used for auth method values on the wire.", "type": "string" }, - "AuthEnvVar": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nDescribes a single environment variable for an [`AuthMethodEnvVar`] authentication method.", - "type": "object", - "properties": { - "name": { - "description": "The environment variable name (e.g. `\"OPENAI_API_KEY\"`).", - "type": "string" - }, - "label": { - "description": "Human-readable label for this variable, displayed in client UI.", - "type": ["string", "null"], - "x-deserialize-default-on-error": true - }, - "secret": { - "description": "Whether this value is a secret (e.g. API key, token).\nClients should use a password-style input for secret vars.\n\nDefaults to `true`.", - "type": "boolean", - "x-deserialize-default-on-error": true, - "default": true - }, - "optional": { - "description": "Whether this variable is optional.\n\nDefaults to `false`.", - "type": "boolean", - "x-deserialize-default-on-error": true, - "default": false - }, - "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", - "type": ["object", "null"], - "x-deserialize-default-on-error": true, - "additionalProperties": true - } - }, - "required": ["name"] - }, - "AuthMethodEnvVar": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nEnvironment variable authentication method.\n\nThe user provides credentials that the client passes to the agent as environment variables.", - "type": "object", - "properties": { - "methodId": { - "description": "Unique identifier for this authentication method.", - "allOf": [ - { - "$ref": "#/$defs/AuthMethodId" - } - ] - }, - "name": { - "description": "Human-readable name of the authentication method.", - "type": "string" - }, - "description": { - "description": "Optional description providing more details about this authentication method.", - "type": ["string", "null"], - "x-deserialize-default-on-error": true - }, - "vars": { - "description": "The environment variables the client should set.", - "type": "array", - "items": { - "$ref": "#/$defs/AuthEnvVar" - }, - "x-deserialize-default-on-error": true, - "x-deserialize-skip-invalid-items": true - }, - "link": { - "description": "Optional link to a page where the user can obtain their credentials.", - "type": ["string", "null"], - "format": "uri", - "x-deserialize-default-on-error": true - }, - "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", - "type": ["object", "null"], - "x-deserialize-default-on-error": true, - "additionalProperties": true - } - }, - "required": ["methodId", "name", "vars"] - }, "EnvVariable": { - "description": "An environment variable to set when launching an MCP server.", + "description": "An environment variable to set when launching a process.", "type": "object", "properties": { "name": { @@ -4417,7 +4312,7 @@ "required": ["name", "value"] }, "AuthMethodTerminal": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nTerminal-based authentication method.\n\nThe client runs an interactive terminal for the user to authenticate via a TUI.", + "description": "Terminal-based authentication method.\n\nThe client runs the configured agent program as a separate interactive\nprocess for the user to authenticate via a TUI. Agents MUST advertise this\nmethod only when the client enabled its terminal authentication capability.\nA zero exit status signals success; any other termination signals failure.\nThe client MUST NOT pass this method to `auth/login`.", "type": "object", "properties": { "methodId": { @@ -4438,7 +4333,7 @@ "x-deserialize-default-on-error": true }, "args": { - "description": "Additional arguments to pass when running the agent binary for terminal auth.", + "description": "Additional arguments to append to the configured agent invocation for terminal auth.", "type": "array", "items": { "type": "string" @@ -4447,7 +4342,7 @@ "x-deserialize-skip-invalid-items": true }, "env": { - "description": "Additional environment variables to set when running the agent binary for terminal auth.", + "description": "Additional environment variables to set on the configured agent invocation for terminal auth.\nNames MUST be unique. These values override same-named variables in the\nbase launch configuration.", "type": "array", "items": { "$ref": "#/$defs/EnvVariable" @@ -4465,7 +4360,7 @@ "required": ["methodId", "name"] }, "AuthMethodAgent": { - "description": "Agent handles authentication itself.\n\nThe `type` discriminator value is `agent`.", + "description": "Agent handles authentication itself through `auth/login`.\n\nThe `type` discriminator value is `agent`.", "type": "object", "properties": { "methodId": { @@ -5753,7 +5648,7 @@ }, { "title": "CompleteElicitationNotification", - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nNotification that a URL-based elicitation has completed.", + "description": "Notification that a URL-based elicitation has completed.\n\nSee protocol docs: [Elicitation](https://agentclientprotocol.com/protocol/v2/draft/elicitation#url-completion)", "allOf": [ { "$ref": "#/$defs/CompleteElicitationNotification" @@ -6095,6 +5990,38 @@ } ] }, + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA context compaction has been created or updated.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "compaction_update" + } + }, + "required": ["sessionUpdate"], + "allOf": [ + { + "$ref": "#/$defs/CompactionUpdate" + } + ] + }, + { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA content block appended to a context compaction's retained summary.", + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "compaction_summary_chunk" + } + }, + "required": ["sessionUpdate"], + "allOf": [ + { + "$ref": "#/$defs/CompactionSummaryChunk" + } + ] + }, { "title": "other", "description": "Custom or future session update.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Unknown values that do not begin with `_` are reserved for\nfuture ACP variants.\n\nReceivers that do not understand this update type should preserve the\nraw payload when storing, replaying, proxying, or forwarding session\nhistory, and otherwise ignore it or display it generically.", @@ -6277,6 +6204,26 @@ } }, "required": ["sessionUpdate"] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "compaction_update" + } + }, + "required": ["sessionUpdate"] + }, + { + "type": "object", + "properties": { + "sessionUpdate": { + "type": "string", + "const": "compaction_summary_chunk" + } + }, + "required": ["sessionUpdate"] } ] }, @@ -7361,8 +7308,114 @@ }, "required": ["used", "size"] }, + "CompactionId": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nUnique identifier for a context compaction within a session.", + "type": "string" + }, + "CompactionStatus": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nLifecycle state of a context compaction.", + "anyOf": [ + { + "description": "Compaction has started and has not finished.", + "type": "string", + "const": "in_progress" + }, + { + "description": "Compaction finished successfully.", + "type": "string", + "const": "completed" + }, + { + "description": "Compaction finished unsuccessfully.", + "type": "string", + "const": "failed" + }, + { + "description": "Compaction was cancelled before it finished.", + "type": "string", + "const": "cancelled" + }, + { + "title": "other", + "description": "Custom or future compaction status.\n\nValues beginning with `_` are reserved for implementation-specific\nextensions. Other unknown values are reserved for future ACP statuses.", + "type": "string" + } + ] + }, + "CompactionUpdate": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA context compaction upsert. The first update fixes the compaction's\ntimeline position. Later updates with the same ID patch that entity in place.\n\n`summary`, `error`, and `_meta` have patch semantics: omission leaves the\nstored value unchanged, `null` clears it, and a concrete value replaces it.\n`summary: []` also clears the retained summary. A non-empty summary is only\nvalid with `completed`; `error` is only valid with `failed`.", + "type": "object", + "properties": { + "compactionId": { + "description": "The Agent-owned ID of this compaction, unique within the session.", + "allOf": [ + { + "$ref": "#/$defs/CompactionId" + } + ] + }, + "status": { + "description": "Current lifecycle status.", + "allOf": [ + { + "$ref": "#/$defs/CompactionStatus" + } + ] + }, + "summary": { + "description": "Complete replacement user-displayable summary retained by the compaction.", + "type": ["array", "null"], + "items": { + "$ref": "#/$defs/ContentBlock" + }, + "x-deserialize-default-on-error": true, + "x-deserialize-skip-invalid-items": true + }, + "error": { + "description": "Human-readable description of why the compaction failed.", + "type": ["string", "null"], + "x-deserialize-default-on-error": true + }, + "_meta": { + "description": "Extensible metadata patch for this compaction.", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": ["compactionId", "status"] + }, + "CompactionSummaryChunk": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA content block appended to the retained summary of an in-progress\ncompaction. Agents send chunks only after an `in_progress` update and before\nthe terminal update for the same ID.", + "type": "object", + "properties": { + "compactionId": { + "description": "ID of the compaction whose summary receives this content.", + "allOf": [ + { + "$ref": "#/$defs/CompactionId" + } + ] + }, + "content": { + "description": "One content block to append.", + "allOf": [ + { + "$ref": "#/$defs/ContentBlock" + } + ] + }, + "_meta": { + "description": "Metadata scoped to this chunk. Omission and `null` both mean absent.", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": ["compactionId", "content"] + }, "CompleteElicitationNotification": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nNotification sent by the agent when a URL-based elicitation is complete.", + "description": "Notification sent by the agent when a URL-based elicitation is complete.", "type": "object", "properties": { "elicitationId": { @@ -7374,7 +7427,7 @@ ] }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -7453,7 +7506,7 @@ }, { "title": "LoginAuthRequest", - "description": "Authenticates the client using the specified authentication method.\n\nAgents MUST support this method when their `initialize` response advertised\nat least one valid authentication method. Clients MUST NOT call this method\nwhen `authMethods` was omitted or empty.\n\nCalled when the agent requires authentication before allowing session creation.\nThe client provides the authentication method ID that was advertised during initialization.\n\nAfter successful authentication, the client can proceed to create sessions with\n`new_session` without receiving an `auth_required` error.\n\nSee protocol docs: [Initialization](https://agentclientprotocol.com/protocol/v2/draft/initialization)", + "description": "Authenticates the client using the specified authentication method.\n\nAgents MUST support this method when their `initialize` response advertised\nat least one valid authentication method. Clients MUST call this method only\nwith a method whose type defines a protocol-driven login flow, and MUST NOT\ncall it when `authMethods` was omitted or empty.\n\nCalled when the agent requires authentication before allowing session creation.\nThe client provides the authentication method ID that was advertised during initialization.\n\nAfter successful authentication, the client can proceed to create sessions with\n`new_session` without receiving an `auth_required` error.\n\nSee protocol docs: [Initialization](https://agentclientprotocol.com/protocol/v2/draft/initialization)", "allOf": [ { "$ref": "#/$defs/LoginAuthRequest" @@ -7489,7 +7542,7 @@ }, { "title": "LogoutAuthRequest", - "description": "Logs out of the current authenticated state.\n\nAgents MUST support this method when their `initialize` response advertised\nat least one valid authentication method. Clients MUST NOT call this method\nwhen `authMethods` was omitted or empty.\n\nAfter a successful logout, authentication-gated requests require the client\nto authenticate again. There is no guarantee about the behavior of already\nrunning sessions.", + "description": "Logs out of the current authenticated state.\n\nAgents MUST support this method when their `initialize` response advertised\nat least one valid authentication method. Clients MUST NOT call this method\nwhen `authMethods` was omitted or empty.\n\nAfter a successful logout, authentication-gated requests require the\nclient to complete an advertised authentication flow again. There is no\nguarantee about the behavior of already running sessions.", "allOf": [ { "$ref": "#/$defs/LogoutAuthRequest" @@ -7670,7 +7723,7 @@ "type": "object", "properties": { "auth": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAuthentication 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 or `null` both mean the client does not advertise any\nauthentication-method extensions.", "anyOf": [ { "$ref": "#/$defs/AuthCapabilities" @@ -7682,7 +7735,7 @@ "x-deserialize-default-on-error": true }, "elicitation": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nElicitation 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 or `null` both mean the client does not advertise\nelicitation support.", "anyOf": [ { "$ref": "#/$defs/ElicitationCapabilities" @@ -7723,11 +7776,11 @@ } }, "AuthCapabilities": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAuthentication capabilities supported by the client.\n\nAdvertised during initialization to inform the agent which authentication\nmethod types the client can handle. This governs opt-in types that require\nadditional client-side support.", + "description": "Authentication capabilities supported by the client.\n\nAdvertised during initialization to inform the agent which authentication\nmethod types the client can handle. This governs opt-in types that require\nadditional client-side support.", "type": "object", "properties": { "terminal": { - "description": "Whether the client supports `terminal` authentication methods.\n\nOptional. Omitted or `null` both mean the client does not advertise support.\nSupplying `{}` means the agent may include `terminal` entries in its authentication methods.", + "description": "Whether the client supports `terminal` authentication methods.\n\nOptional. Omitted or `null` both mean the client does not advertise support.\nThe client should supply `{}` only when it can reproduce the configured\nagent invocation in an interactive terminal. Supplying `{}` means the\nagent may include `terminal` entries in its authentication methods.", "anyOf": [ { "$ref": "#/$defs/TerminalAuthCapabilities" @@ -7747,7 +7800,7 @@ } }, "TerminalAuthCapabilities": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapabilities for terminal authentication methods.\n\nSupplying `{}` means the client supports terminal authentication methods.", + "description": "Capabilities for terminal authentication methods.\n\nSupplying `{}` means the client can reproduce the configured agent\ninvocation in an interactive terminal and supports terminal authentication\nmethods.", "type": "object", "properties": { "_meta": { @@ -7759,11 +7812,11 @@ } }, "ElicitationCapabilities": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nElicitation capabilities supported by the client.", + "description": "Elicitation capabilities supported by the client.", "type": "object", "properties": { "form": { - "description": "Whether the client supports form-based elicitation.\n\nOptional. Omitted or `null` both mean the client does not advertise support.\nSupplying `{}` means the client supports form-based elicitation.", + "description": "Whether the client supports form-based elicitation.\n\nOptional. Omitted and `null` are equivalent and mean form support is not advertised.\nSupplying `{}` explicitly advertises form support.", "anyOf": [ { "$ref": "#/$defs/ElicitationFormCapabilities" @@ -7787,7 +7840,7 @@ "x-deserialize-default-on-error": true }, "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -7795,11 +7848,11 @@ } }, "ElicitationFormCapabilities": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nForm-based elicitation capabilities.\n\nSupplying `{}` means the client supports form-based elicitation.", + "description": "Form-based elicitation capabilities.\n\nSupplying `{}` means the client supports form-based elicitation.", "type": "object", "properties": { "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -7807,11 +7860,11 @@ } }, "ElicitationUrlCapabilities": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nURL-based elicitation capabilities.\n\nSupplying `{}` means the client supports URL-based elicitation.", + "description": "URL-based elicitation capabilities.\n\nSupplying `{}` means the client supports URL-based elicitation.", "type": "object", "properties": { "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -9394,11 +9447,11 @@ "required": ["optionId"] }, "CreateElicitationResponse": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse from the client to an elicitation request.", + "description": "Response from the client to an elicitation request.", "type": "object", "properties": { "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nOptional. Omitted and `null` are equivalent and mean no metadata.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", "type": ["object", "null"], "x-deserialize-default-on-error": true, "additionalProperties": true @@ -9530,7 +9583,7 @@ ] }, "ElicitationAcceptAction": { - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe user accepted the elicitation and provided content.", + "description": "The user accepted the elicitation and provided content.", "type": "object", "properties": { "content": { diff --git a/scripts/generate.js b/scripts/generate.js index ae7c3dee..2ac993cd 100644 --- a/scripts/generate.js +++ b/scripts/generate.js @@ -10,8 +10,8 @@ import * as fs from "fs/promises"; import { dirname } from "path"; import * as prettier from "prettier"; -const CURRENT_V1_SCHEMA_RELEASE = "schema-v1.20.0"; -const CURRENT_V2_SCHEMA_RELEASE = "schema-v2.0.0-alpha.2"; +const CURRENT_V1_SCHEMA_RELEASE = "schema-v1.21.0"; +const CURRENT_V2_SCHEMA_RELEASE = "schema-v2.0.0-alpha.3"; const CHECK_GENERATED = process.argv.includes("--check"); // ── Extensible-union pipeline ──────────────────────────────────────────────── diff --git a/src/acp.test.ts b/src/acp.test.ts index 796199d8..1021feb4 100644 --- a/src/acp.test.ts +++ b/src/acp.test.ts @@ -2685,8 +2685,8 @@ describe("Connection", () => { async function exerciseElicitation(agentClient: AgentSideConnection) { const response = - await agentClient.unstable_createElicitation(elicitationRequest); - await agentClient.unstable_completeElicitation({ + await agentClient.createElicitation(elicitationRequest); + await agentClient.completeElicitation({ elicitationId: "elicitation-1", }); return response; @@ -2699,14 +2699,14 @@ describe("Connection", () => { return { outcome: { outcome: "cancelled" } }; }, sessionUpdate(): void {}, - unstable_createElicitation(params) { + createElicitation(params) { received.push(["create", params.message]); return { action: "accept", content: { name: "Alice" }, }; }, - unstable_completeElicitation(params) { + completeElicitation(params) { received.push(["complete", params.elicitationId]); }, }), @@ -5910,7 +5910,7 @@ describe("Connection", () => { } async sessionUpdate(_: SessionNotification): Promise {} - async unstable_createElicitation( + async createElicitation( params: CreateElicitationRequest, ): Promise { receivedRequest = params; @@ -5919,7 +5919,7 @@ describe("Connection", () => { content: { name: "Alice" }, }; } - async unstable_completeElicitation( + async completeElicitation( params: CompleteElicitationNotification, ): Promise { receivedNotification = params; @@ -5954,7 +5954,7 @@ describe("Connection", () => { ); // Test form-mode elicitation request - const response = await clientConnection.unstable_createElicitation({ + const response = await clientConnection.createElicitation({ sessionId: "test-session", mode: "form", message: "Please enter your name", @@ -5973,7 +5973,7 @@ describe("Connection", () => { // Test url-mode elicitation request receivedRequest = undefined; - const urlResponse = await clientConnection.unstable_createElicitation({ + const urlResponse = await clientConnection.createElicitation({ sessionId: "test-session", mode: "url", message: "Please authenticate", @@ -5988,7 +5988,7 @@ describe("Connection", () => { expect((receivedRequest as any)?.elicitationId).toBe("elic-url-1"); // Test elicitation complete notification - await clientConnection.unstable_completeElicitation({ + await clientConnection.completeElicitation({ elicitationId: "elic-1", }); @@ -6044,13 +6044,13 @@ describe("Connection", () => { ndJsonStream(agentToClient.writable, clientToAgent.readable), ); - await clientConnection.unstable_completeElicitation({ + await clientConnection.completeElicitation({ elicitationId: "elic-1", }); }); it("rejects elicitation request when client does not implement handler", async () => { - // Client WITHOUT unstable_createElicitation + // Client WITHOUT createElicitation class TestClient implements Client { async writeTextFile( _: WriteTextFileRequest, @@ -6098,7 +6098,7 @@ describe("Connection", () => { ); await expect( - clientConnection.unstable_createElicitation({ + clientConnection.createElicitation({ sessionId: "test-session", mode: "form", message: "Enter your name", diff --git a/src/acp.ts b/src/acp.ts index e816d2a5..eb6aa189 100644 --- a/src/acp.ts +++ b/src/acp.ts @@ -1378,7 +1378,7 @@ const clientRequestSpecs = { validate.zKillTerminalRequest, emptyObjectResponse, ), - unstable_createElicitation: requestSpec< + createElicitation: requestSpec< schema.CreateElicitationRequest, schema.CreateElicitationResponse >( @@ -1392,11 +1392,10 @@ const clientNotificationSpecs = { schema.CLIENT_METHODS.session_update, validate.zSessionNotification, ), - unstable_completeElicitation: - notificationSpec( - schema.CLIENT_METHODS.elicitation_complete, - validate.zCompleteElicitationNotification, - ), + completeElicitation: notificationSpec( + schema.CLIENT_METHODS.elicitation_complete, + validate.zCompleteElicitationNotification, + ), }; const agentRequestSpecsByMethod = specsByMethod(agentRequestSpecs); @@ -2605,14 +2604,14 @@ function legacyClientApp(implementation: Client): ClientApp { async (ctx) => (await implementation.killTerminal?.(ctx.params)) ?? {}, ); - if (implementation.unstable_createElicitation) { + if (implementation.createElicitation) { app.onRequest(schema.CLIENT_METHODS.elicitation_create, (ctx) => - implementation.unstable_createElicitation!(ctx.params), + implementation.createElicitation!(ctx.params), ); } - if (implementation.unstable_completeElicitation) { + if (implementation.completeElicitation) { app.onNotification(schema.CLIENT_METHODS.elicitation_complete, (ctx) => - implementation.unstable_completeElicitation!(ctx.params), + implementation.completeElicitation!(ctx.params), ); } @@ -2799,16 +2798,8 @@ export class AgentSideConnection { ); } - /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * - * Creates an elicitation to request input from the user. - * - * @experimental - */ - unstable_createElicitation( + /** Creates an elicitation to request input from the user. */ + createElicitation( params: schema.CreateElicitationRequest, ): Promise { return this.connection.sendRequest( @@ -2817,16 +2808,8 @@ export class AgentSideConnection { ); } - /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * - * Notifies the client that a URL-based elicitation is complete. - * - * @experimental - */ - unstable_completeElicitation( + /** Notifies the client that a URL-based elicitation is complete. */ + completeElicitation( params: schema.CompleteElicitationNotification, ): Promise { return this.connection.sendNotification( @@ -3860,29 +3843,13 @@ export interface Client { params: schema.KillTerminalRequest, ): MaybePromise; - /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * - * Creates an elicitation to request input from the user. - * - * @experimental - */ - unstable_createElicitation?( + /** Creates an elicitation to request input from the user. */ + createElicitation?( params: schema.CreateElicitationRequest, ): MaybePromise; - /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * - * Called when a URL-based elicitation is complete. - * - * @experimental - */ - unstable_completeElicitation?( + /** Called when a URL-based elicitation is complete. */ + completeElicitation?( params: schema.CompleteElicitationNotification, ): MaybePromise; diff --git a/src/schema/guards.gen.ts b/src/schema/guards.gen.ts index 2c0499ac..2acda1d9 100644 --- a/src/schema/guards.gen.ts +++ b/src/schema/guards.gen.ts @@ -48,17 +48,11 @@ const zGuardCreateElicitationResponseCancel = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Request from the agent to elicit structured user input. * * The agent sends this to the client to request information from the user, * either via a form or by directing them to a URL. * Elicitations are tied to a session (optionally a tool call) or a request. - * - * @experimental */ export type CreateElicitationRequest = types.CreateElicitationRequest; /** @@ -75,8 +69,6 @@ export type CreateElicitationRequest = types.CreateElicitationRequest; * another variant's payload) guards are conservative where wire parsing * may still accept the value — narrow wire-parsed values when exact * parity matters. - * - * @experimental */ export const CreateElicitationRequest = { /** Narrow to the `form` variant, validating its payload. */ @@ -271,13 +263,7 @@ export const MultiSelectItems = { } as const; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Response from the client to an elicitation request. - * - * @experimental */ export type CreateElicitationResponse = types.CreateElicitationResponse; /** @@ -294,8 +280,6 @@ export type CreateElicitationResponse = types.CreateElicitationResponse; * another variant's payload) guards are conservative where wire parsing * may still accept the value — narrow wire-parsed values when exact * parity matters. - * - * @experimental */ export const CreateElicitationResponse = { /** Narrow to the `accept` variant, validating its payload. */ diff --git a/src/schema/index.ts b/src/schema/index.ts index d0ff0cd8..8c54f917 100644 --- a/src/schema/index.ts +++ b/src/schema/index.ts @@ -12,10 +12,8 @@ export type { AuthCapabilities, AuthenticateRequest, AuthenticateResponse, - AuthEnvVar, AuthMethod, AuthMethodAgent, - AuthMethodEnvVar, AuthMethodId, AuthMethodTerminal, AvailableCommand, @@ -36,6 +34,11 @@ export type { CloseNesResponse, CloseSessionRequest, CloseSessionResponse, + CompactionCapabilities, + CompactionId, + CompactionStatus, + CompactionSummaryChunk, + CompactionUpdate, CompleteElicitationNotification, ConfigOptionUpdate, ConnectMcpRequest, diff --git a/src/schema/types.gen.ts b/src/schema/types.gen.ts index ca1e9b27..e8424cee 100644 --- a/src/schema/types.gen.ts +++ b/src/schema/types.gen.ts @@ -874,17 +874,11 @@ export type KillTerminalRequest = { }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Request from the agent to elicit structured user input. * * The agent sends this to the client to request information from the user, * either via a form or by directing them to a URL. * Elicitations are tied to a session (optionally a tool call) or a request. - * - * @experimental */ export type CreateElicitationRequest = ( | (ElicitationFormMode & { @@ -914,6 +908,8 @@ export type CreateElicitationRequest = ( * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) */ _meta?: { @@ -922,17 +918,11 @@ export type CreateElicitationRequest = ( }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Session-scoped elicitation, optionally tied to a specific tool call. * * When `tool_call_id` is set, the elicitation is tied to a specific tool call. * This is useful when an agent receives an elicitation from an MCP server * during a tool call and needs to redirect it to the user. - * - * @experimental */ export type ElicitationSessionScope = { /** @@ -941,19 +931,16 @@ export type ElicitationSessionScope = { sessionId: SessionId; /** * Optional tool call within the session. + * + * Optional. Omitted and `null` are equivalent and mean the elicitation is scoped to the + * session without a specific tool call. */ toolCallId?: ToolCallId | null; }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Request-scoped elicitation, tied to a specific JSON-RPC request outside of a session * (e.g., during auth/configuration phases before any session is started). - * - * @experimental */ export type ElicitationRequestScope = { /** @@ -975,6 +962,8 @@ export type ElicitationSchema = { type?: ElicitationSchemaType; /** * Optional title for the schema. + * + * Optional. Omitted and `null` are equivalent and mean no title is provided. */ title?: string | null; /** @@ -985,10 +974,14 @@ export type ElicitationSchema = { }; /** * List of required property names. + * + * Optional. Omitted and `null` are equivalent and mean no property names are required. */ required?: Array | null; /** * Optional description of what this schema represents. + * + * Optional. Omitted and `null` are equivalent and mean no schema description is provided. */ description?: string | null; /** @@ -996,6 +989,8 @@ export type ElicitationSchema = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) */ _meta?: { @@ -1062,6 +1057,8 @@ export type EnumOption = { title: string; /** * Human-readable description. + * + * Optional. Omitted and `null` are equivalent and mean no description is provided. */ description?: string | null; /** @@ -1069,6 +1066,8 @@ export type EnumOption = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) */ _meta?: { @@ -1085,38 +1084,56 @@ export type EnumOption = { export type StringPropertySchema = { /** * Optional title for the property. + * + * Optional. Omitted and `null` are equivalent and mean no title is provided. */ title?: string | null; /** * Human-readable description. + * + * Optional. Omitted and `null` are equivalent and mean no description is provided. */ description?: string | null; /** * Minimum string length. + * + * Optional. Omitted and `null` are equivalent and mean there is no minimum length constraint. */ minLength?: number | null; /** * Maximum string length. + * + * Optional. Omitted and `null` are equivalent and mean there is no maximum length constraint. */ maxLength?: number | null; /** * Pattern the string must match. + * + * Optional. Omitted and `null` are equivalent and mean there is no pattern constraint. */ pattern?: string | null; /** * String format. + * + * Optional. Omitted and `null` are equivalent and mean there is no format constraint. */ format?: StringFormat | null; /** * Default value. + * + * Optional. Omitted and `null` are equivalent and mean no default value is provided. */ default?: string | null; /** * Enum values for untitled single-select enums. + * Optional. Omitted and `null` are equivalent and mean no untitled single-select choices are + * declared by `enum`. */ enum?: Array | null; /** * Titled enum options for titled single-select enums. + * Optional. Omitted and `null` are equivalent and mean no titled single-select choices are + * declared by `oneOf`. */ oneOf?: Array | null; /** @@ -1124,6 +1141,8 @@ export type StringPropertySchema = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) */ _meta?: { @@ -1137,22 +1156,32 @@ export type StringPropertySchema = { export type NumberPropertySchema = { /** * Optional title for the property. + * + * Optional. Omitted and `null` are equivalent and mean no title is provided. */ title?: string | null; /** * Human-readable description. + * + * Optional. Omitted and `null` are equivalent and mean no description is provided. */ description?: string | null; /** * Minimum value (inclusive). + * + * Optional. Omitted and `null` are equivalent and mean there is no inclusive lower bound. */ minimum?: number | null; /** * Maximum value (inclusive). + * + * Optional. Omitted and `null` are equivalent and mean there is no inclusive upper bound. */ maximum?: number | null; /** * Default value. + * + * Optional. Omitted and `null` are equivalent and mean no default value is provided. */ default?: number | null; /** @@ -1160,6 +1189,8 @@ export type NumberPropertySchema = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) */ _meta?: { @@ -1173,22 +1204,32 @@ export type NumberPropertySchema = { export type IntegerPropertySchema = { /** * Optional title for the property. + * + * Optional. Omitted and `null` are equivalent and mean no title is provided. */ title?: string | null; /** * Human-readable description. + * + * Optional. Omitted and `null` are equivalent and mean no description is provided. */ description?: string | null; /** * Minimum value (inclusive). + * + * Optional. Omitted and `null` are equivalent and mean there is no inclusive lower bound. */ minimum?: number | null; /** * Maximum value (inclusive). + * + * Optional. Omitted and `null` are equivalent and mean there is no inclusive upper bound. */ maximum?: number | null; /** * Default value. + * + * Optional. Omitted and `null` are equivalent and mean no default value is provided. */ default?: number | null; /** @@ -1196,6 +1237,8 @@ export type IntegerPropertySchema = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) */ _meta?: { @@ -1209,14 +1252,20 @@ export type IntegerPropertySchema = { export type BooleanPropertySchema = { /** * Optional title for the property. + * + * Optional. Omitted and `null` are equivalent and mean no title is provided. */ title?: string | null; /** * Human-readable description. + * + * Optional. Omitted and `null` are equivalent and mean no description is provided. */ description?: string | null; /** * Default value. + * + * Optional. Omitted and `null` are equivalent and mean no default value is provided. */ default?: boolean | null; /** @@ -1224,6 +1273,8 @@ export type BooleanPropertySchema = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) */ _meta?: { @@ -1264,6 +1315,8 @@ export type StringMultiSelectItems = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) */ _meta?: { @@ -1284,6 +1337,8 @@ export type TitledMultiSelectItems = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) */ _meta?: { @@ -1297,18 +1352,26 @@ export type TitledMultiSelectItems = { export type MultiSelectPropertySchema = { /** * Optional title for the property. + * + * Optional. Omitted and `null` are equivalent and mean no title is provided. */ title?: string | null; /** * Human-readable description. + * + * Optional. Omitted and `null` are equivalent and mean no description is provided. */ description?: string | null; /** * Minimum number of items to select. + * + * Optional. Omitted and `null` are equivalent and mean there is no minimum selection count. */ minItems?: number | null; /** * Maximum number of items to select. + * + * Optional. Omitted and `null` are equivalent and mean there is no maximum selection count. */ maxItems?: number | null; /** @@ -1317,6 +1380,8 @@ export type MultiSelectPropertySchema = { items: MultiSelectItems; /** * Default selected values. + * + * Optional. Omitted and `null` are equivalent and mean no default selections are provided. */ default?: Array | null; /** @@ -1324,6 +1389,8 @@ export type MultiSelectPropertySchema = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) */ _meta?: { @@ -1332,13 +1399,7 @@ export type MultiSelectPropertySchema = { }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Form-based elicitation mode where the client renders a form from the provided schema. - * - * @experimental */ export type ElicitationFormMode = ( ElicitationSessionScope | ElicitationRequestScope @@ -1350,24 +1411,12 @@ export type ElicitationFormMode = ( }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Unique identifier for an elicitation. - * - * @experimental */ export type ElicitationId = string; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * URL-based elicitation mode where the client directs the user to a URL. - * - * @experimental */ export type ElicitationUrlMode = ( ElicitationSessionScope | ElicitationRequestScope @@ -2345,9 +2394,6 @@ export type PositionEncodingKind = "utf-16" | "utf-32" | "utf-8"; * When no `type` is present, the method is treated as `agent`. */ export type AuthMethod = - | (AuthMethodEnvVar & { - type: "env_var"; - }) | (AuthMethodTerminal & { type: "terminal"; }) @@ -2359,102 +2405,13 @@ export type AuthMethod = export type AuthMethodId = string; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * - * Describes a single environment variable for an [`AuthMethodEnvVar`] authentication method. - * - * @experimental - */ -export type AuthEnvVar = { - /** - * The environment variable name (e.g. `"OPENAI_API_KEY"`). - */ - name: string; - /** - * Human-readable label for this variable, displayed in client UI. - */ - label?: string | null; - /** - * Whether this value is a secret (e.g. API key, token). - * Clients should use a password-style input for secret vars. - * - * Defaults to `true`. - */ - secret?: boolean; - /** - * Whether this variable is optional. - * - * Defaults to `false`. - */ - optional?: boolean; - /** - * The _meta property is reserved by ACP to allow clients and agents to attach additional - * metadata to their interactions. Implementations MUST NOT make assumptions about values at - * these keys. - * - * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - */ - _meta?: { - [key: string]: unknown; - } | null; -}; - -/** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * - * Environment variable authentication method. - * - * The user provides credentials that the client passes to the agent as environment variables. - * - * @experimental - */ -export type AuthMethodEnvVar = { - /** - * Unique identifier for this authentication method. - */ - id: AuthMethodId; - /** - * Human-readable name of the authentication method. - */ - name: string; - /** - * Optional description providing more details about this authentication method. - */ - description?: string | null; - /** - * The environment variables the client should set. - */ - vars: Array; - /** - * Optional link to a page where the user can obtain their credentials. - */ - link?: string | null; - /** - * The _meta property is reserved by ACP to allow clients and agents to attach additional - * metadata to their interactions. Implementations MUST NOT make assumptions about values at - * these keys. - * - * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) - */ - _meta?: { - [key: string]: unknown; - } | null; -}; - -/** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Terminal-based authentication method. * - * The client runs an interactive terminal for the user to authenticate via a TUI. - * - * @experimental + * The client runs the configured agent program as a separate interactive + * process for the user to authenticate via a TUI. Agents MUST advertise this + * method only when the client enabled its terminal authentication capability. + * A zero exit status signals success; any other termination signals failure. + * The client MUST NOT pass this method to `authenticate`. */ export type AuthMethodTerminal = { /** @@ -2470,11 +2427,12 @@ export type AuthMethodTerminal = { */ description?: string | null; /** - * Additional arguments to pass when running the agent binary for terminal auth. + * Additional arguments to append to the configured agent invocation for terminal auth. */ args?: Array; /** - * Additional environment variables to set when running the agent binary for terminal auth. + * Additional environment variables to set on the configured agent invocation for terminal auth. + * These values override same-named variables in the base launch configuration. */ env?: { [key: string]: string; @@ -2492,7 +2450,7 @@ export type AuthMethodTerminal = { }; /** - * Agent handles authentication itself. + * Agent handles authentication itself through `authenticate`. * * This is the default authentication method type. */ @@ -3748,6 +3706,12 @@ export type SessionUpdate = }) | (UsageUpdate & { sessionUpdate: "usage_update"; + }) + | (CompactionUpdate & { + sessionUpdate: "compaction_update"; + }) + | (CompactionSummaryChunk & { + sessionUpdate: "compaction_summary_chunk"; }); /** @@ -4306,10 +4270,98 @@ export type UsageUpdate = { * * This capability is not part of the spec yet, and may be removed or changed at any point. * - * Notification sent by the agent when a URL-based elicitation is complete. + * Unique identifier for a context compaction within a session. + * + * @experimental + */ +export type CompactionId = string; + +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Lifecycle state of a context compaction. + * + * @experimental + */ +export type CompactionStatus = + "in_progress" | "completed" | "failed" | "cancelled" | string; + +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * A context compaction upsert. The first update fixes the compaction's + * timeline position. Later updates with the same ID patch that entity in place. + * Agents MUST only send this update when the Client advertised + * [`ClientSessionCapabilities::compaction`]. + * + * `summary`, `error`, and `_meta` have patch semantics: omission leaves the + * stored value unchanged, `null` clears it, and a concrete value replaces it. + * `summary: []` also clears the retained summary. A non-empty summary is only + * valid with `completed`; `error` is only valid with `failed`. * * @experimental */ +export type CompactionUpdate = { + /** + * The Agent-owned ID of this compaction, unique within the session. + */ + compactionId: CompactionId; + /** + * Current lifecycle status. + */ + status: CompactionStatus; + /** + * Complete replacement user-displayable summary retained by the compaction. + */ + summary?: Array | null; + /** + * Human-readable description of why the compaction failed. + */ + error?: string | null; + /** + * Extensible metadata patch for this compaction. + */ + _meta?: { + [key: string]: unknown; + } | null; +}; + +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * A content block appended to the retained summary of an in-progress + * compaction. Agents send chunks only after an `in_progress` update and before + * the terminal update for the same ID. Agents MUST only send this update when + * the Client advertised [`ClientSessionCapabilities::compaction`]. + * + * @experimental + */ +export type CompactionSummaryChunk = { + /** + * ID of the compaction whose summary receives this content. + */ + compactionId: CompactionId; + /** + * One content block to append. + */ + content: ContentBlock; + /** + * Metadata scoped to this chunk. Omission and `null` both mean absent. + */ + _meta?: { + [key: string]: unknown; + } | null; +}; + +/** + * Notification sent by the agent when a URL-based elicitation is complete. + */ export type CompleteElicitationNotification = { /** * The ID of the elicitation that completed. @@ -4320,6 +4372,8 @@ export type CompleteElicitationNotification = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) */ _meta?: { @@ -4490,29 +4544,17 @@ export type ClientCapabilities = { */ plan?: PlanCapabilities | null; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Authentication capabilities supported by the client. * Determines which authentication method types the agent may include * in its `InitializeResponse`. - * - * @experimental */ auth?: AuthCapabilities; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Elicitation capabilities supported by the client. * Determines which elicitation modes the agent may use. * * Optional. Omitted or `null` both mean the client does not advertise * elicitation support. - * - * @experimental */ elicitation?: ElicitationCapabilities | null; /** @@ -4580,6 +4622,17 @@ export type FileSystemCapabilities = { * Session-related capabilities supported by the client. */ export type ClientSessionCapabilities = { + /** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Support for ID-addressed context compaction updates. Omitted or `null` + * means unsupported; `{}` advertises the complete compaction contract. + * + * @experimental + */ + compaction?: CompactionCapabilities | null; /** * Config option capabilities supported by the client. * @@ -4599,6 +4652,19 @@ export type ClientSessionCapabilities = { } | null; }; +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Client support for ID-addressed context compaction updates. + * + * @experimental + */ +export type CompactionCapabilities = { + [key: string]: unknown; +}; + /** * Session configuration option capabilities supported by the client. */ @@ -4665,23 +4731,19 @@ export type PlanCapabilities = { }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Authentication capabilities supported by the client. * * Advertised during initialization to inform the agent which authentication * method types the client can handle. This governs opt-in types that require * additional client-side support. - * - * @experimental */ export type AuthCapabilities = { /** * Whether the client supports `terminal` authentication methods. * - * When `true`, the agent may include `terminal` entries in its authentication methods. + * The client should set this to `true` only when it can reproduce the + * configured agent invocation in an interactive terminal. When `true`, the + * agent may include `terminal` entries in its authentication methods. */ terminal?: boolean; /** @@ -4697,20 +4759,14 @@ export type AuthCapabilities = { }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Elicitation capabilities supported by the client. - * - * @experimental */ export type ElicitationCapabilities = { /** * Whether the client supports form-based elicitation. * - * Optional. Omitted or `null` both mean the client does not advertise support. - * Supplying `{}` means the client supports form-based elicitation. + * Optional. Omitted and `null` are equivalent and mean form support is not advertised. + * Supplying `{}` explicitly advertises form support. */ form?: ElicitationFormCapabilities | null; /** @@ -4725,6 +4781,8 @@ export type ElicitationCapabilities = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) */ _meta?: { @@ -4733,15 +4791,9 @@ export type ElicitationCapabilities = { }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Form-based elicitation capabilities. * * Supplying `{}` means the client supports form-based elicitation. - * - * @experimental */ export type ElicitationFormCapabilities = { /** @@ -4749,6 +4801,8 @@ export type ElicitationFormCapabilities = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) */ _meta?: { @@ -4757,15 +4811,9 @@ export type ElicitationFormCapabilities = { }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * URL-based elicitation capabilities. * * Supplying `{}` means the client supports URL-based elicitation. - * - * @experimental */ export type ElicitationUrlCapabilities = { /** @@ -4773,6 +4821,8 @@ export type ElicitationUrlCapabilities = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) */ _meta?: { @@ -6148,13 +6198,7 @@ export type KillTerminalResponse = { }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Response from the client to an elicitation request. - * - * @experimental */ export type CreateElicitationResponse = ( | (ElicitationAcceptAction & { @@ -6183,6 +6227,8 @@ export type CreateElicitationResponse = ( * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility) */ _meta?: { @@ -6197,13 +6243,7 @@ export type ElicitationContentValue = string | number | number | boolean | Array; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * The user accepted the elicitation and provided content. - * - * @experimental */ export type ElicitationAcceptAction = { /** diff --git a/src/schema/zod.gen.ts b/src/schema/zod.gen.ts index e962eedb..12745495 100644 --- a/src/schema/zod.gen.ts +++ b/src/schema/zod.gen.ts @@ -539,17 +539,11 @@ export const zKillTerminalRequest = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Session-scoped elicitation, optionally tied to a specific tool call. * * When `tool_call_id` is set, the elicitation is tied to a specific tool call. * This is useful when an agent receives an elicitation from an MCP server * during a tool call and needs to redirect it to the user. - * - * @experimental */ export const zElicitationSessionScope = z.object({ sessionId: zSessionId, @@ -557,14 +551,8 @@ export const zElicitationSessionScope = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Request-scoped elicitation, tied to a specific JSON-RPC request outside of a session * (e.g., during auth/configuration phases before any session is started). - * - * @experimental */ export const zElicitationRequestScope = z.object({ requestId: zRequestId, @@ -815,13 +803,7 @@ export const zElicitationSchema = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Form-based elicitation mode where the client renders a form from the provided schema. - * - * @experimental */ export const zElicitationFormMode = z.intersection( z.union([zElicitationSessionScope, zElicitationRequestScope]), @@ -831,24 +813,12 @@ export const zElicitationFormMode = z.intersection( ); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Unique identifier for an elicitation. - * - * @experimental */ export const zElicitationId = z.string(); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * URL-based elicitation mode where the client directs the user to a URL. - * - * @experimental */ export const zElicitationUrlMode = z.intersection( z.union([zElicitationSessionScope, zElicitationRequestScope]), @@ -859,18 +829,12 @@ export const zElicitationUrlMode = z.intersection( ); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Request from the agent to elicit structured user input. * * The agent sends this to the client to request information from the user, * either via a form or by directing them to a URL. * Elicitations are tied to a session (optionally a tool call) or a request. * - * @experimental - * * Custom variants (unknown `mode` values) keep their extra * properties exactly as received; unlike known variants, those keys * bypass lenient-field salvage and arrive unvalidated. @@ -1549,64 +1513,13 @@ export const zAgentCapabilities = z.object({ export const zAuthMethodId = z.string(); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * - * Describes a single environment variable for an [`AuthMethodEnvVar`] authentication method. - * - * @experimental - */ -export const zAuthEnvVar = z.object({ - name: z.string(), - label: defaultOnError(z.string().nullish(), () => undefined), - secret: defaultOnError( - z.boolean().optional().default(true), - () => true as const, - ), - optional: defaultOnError( - z.boolean().optional().default(false), - () => false as const, - ), - _meta: defaultOnError( - z.record(z.string(), z.unknown()).nullish(), - () => undefined, - ), -}); - -/** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * - * Environment variable authentication method. - * - * The user provides credentials that the client passes to the agent as environment variables. - * - * @experimental - */ -export const zAuthMethodEnvVar = z.object({ - id: zAuthMethodId, - name: z.string(), - description: defaultOnError(z.string().nullish(), () => undefined), - vars: requiredDefaultOnError(vecSkipError(zAuthEnvVar), () => []), - link: defaultOnError(z.string().nullish(), () => undefined), - _meta: defaultOnError( - z.record(z.string(), z.unknown()).nullish(), - () => undefined, - ), -}); - -/** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Terminal-based authentication method. * - * The client runs an interactive terminal for the user to authenticate via a TUI. - * - * @experimental + * The client runs the configured agent program as a separate interactive + * process for the user to authenticate via a TUI. Agents MUST advertise this + * method only when the client enabled its terminal authentication capability. + * A zero exit status signals success; any other termination signals failure. + * The client MUST NOT pass this method to `authenticate`. */ export const zAuthMethodTerminal = z.object({ id: zAuthMethodId, @@ -1624,7 +1537,7 @@ export const zAuthMethodTerminal = z.object({ }); /** - * Agent handles authentication itself. + * Agent handles authentication itself through `authenticate`. * * This is the default authentication method type. */ @@ -1645,11 +1558,6 @@ export const zAuthMethodAgent = z.object({ * When no `type` is present, the method is treated as `agent`. */ export const zAuthMethod = z.union([ - zAuthMethodEnvVar.and( - z.object({ - type: z.literal("env_var"), - }), - ), zAuthMethodTerminal.and( z.object({ type: z.literal("terminal"), @@ -2807,6 +2715,86 @@ export const zUsageUpdate = z.object({ ), }); +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Unique identifier for a context compaction within a session. + * + * @experimental + */ +export const zCompactionId = z.string(); + +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Lifecycle state of a context compaction. + * + * @experimental + */ +export const zCompactionStatus = z.union([ + z.literal("in_progress"), + z.literal("completed"), + z.literal("failed"), + z.literal("cancelled"), + z.string(), +]); + +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * A context compaction upsert. The first update fixes the compaction's + * timeline position. Later updates with the same ID patch that entity in place. + * Agents MUST only send this update when the Client advertised + * [`ClientSessionCapabilities::compaction`]. + * + * `summary`, `error`, and `_meta` have patch semantics: omission leaves the + * stored value unchanged, `null` clears it, and a concrete value replaces it. + * `summary: []` also clears the retained summary. A non-empty summary is only + * valid with `completed`; `error` is only valid with `failed`. + * + * @experimental + */ +export const zCompactionUpdate = z.object({ + compactionId: zCompactionId, + status: zCompactionStatus, + summary: defaultOnError( + vecSkipError(zContentBlock).nullish(), + () => undefined, + ), + error: defaultOnError(z.string().nullish(), () => undefined), + _meta: defaultOnError( + z.record(z.string(), z.unknown()).nullish(), + () => undefined, + ), +}); + +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * A content block appended to the retained summary of an in-progress + * compaction. Agents send chunks only after an `in_progress` update and before + * the terminal update for the same ID. Agents MUST only send this update when + * the Client advertised [`ClientSessionCapabilities::compaction`]. + * + * @experimental + */ +export const zCompactionSummaryChunk = z.object({ + compactionId: zCompactionId, + content: zContentBlock, + _meta: defaultOnError( + z.record(z.string(), z.unknown()).nullish(), + () => undefined, + ), +}); + /** * Different types of updates that can be sent during session processing. * @@ -2880,6 +2868,16 @@ export const zSessionUpdate = z.union([ sessionUpdate: z.literal("usage_update"), }), ), + zCompactionUpdate.and( + z.object({ + sessionUpdate: z.literal("compaction_update"), + }), + ), + zCompactionSummaryChunk.and( + z.object({ + sessionUpdate: z.literal("compaction_summary_chunk"), + }), + ), ]); /** @@ -2899,13 +2897,7 @@ export const zSessionNotification = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Notification sent by the agent when a URL-based elicitation is complete. - * - * @experimental */ export const zCompleteElicitationNotification = z.object({ elicitationId: zElicitationId, @@ -2984,6 +2976,17 @@ export const zFileSystemCapabilities = z.object({ ), }); +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Client support for ID-addressed context compaction updates. + * + * @experimental + */ +export const zCompactionCapabilities = z.record(z.string(), z.unknown()); + /** * Capabilities for boolean session configuration options. * @@ -3014,6 +3017,10 @@ export const zSessionConfigOptionsCapabilities = z.object({ * Session-related capabilities supported by the client. */ export const zClientSessionCapabilities = z.object({ + compaction: defaultOnError( + zCompactionCapabilities.nullish(), + () => undefined, + ), configOptions: defaultOnError( zSessionConfigOptionsCapabilities.nullish(), () => undefined, @@ -3041,17 +3048,11 @@ export const zPlanCapabilities = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Authentication capabilities supported by the client. * * Advertised during initialization to inform the agent which authentication * method types the client can handle. This governs opt-in types that require * additional client-side support. - * - * @experimental */ export const zAuthCapabilities = z.object({ terminal: defaultOnError( @@ -3065,15 +3066,9 @@ export const zAuthCapabilities = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Form-based elicitation capabilities. * * Supplying `{}` means the client supports form-based elicitation. - * - * @experimental */ export const zElicitationFormCapabilities = z.object({ _meta: defaultOnError( @@ -3083,15 +3078,9 @@ export const zElicitationFormCapabilities = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * URL-based elicitation capabilities. * * Supplying `{}` means the client supports URL-based elicitation. - * - * @experimental */ export const zElicitationUrlCapabilities = z.object({ _meta: defaultOnError( @@ -3101,13 +3090,7 @@ export const zElicitationUrlCapabilities = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Elicitation capabilities supported by the client. - * - * @experimental */ export const zElicitationCapabilities = z.object({ form: defaultOnError(zElicitationFormCapabilities.nullish(), () => undefined), @@ -3987,27 +3970,15 @@ export const zElicitationContentValue = z.union([ ]); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * The user accepted the elicitation and provided content. - * - * @experimental */ export const zElicitationAcceptAction = z.object({ content: z.record(z.string(), zElicitationContentValue).nullish(), }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Response from the client to an elicitation request. * - * @experimental - * * Custom variants (unknown `action` values) keep their extra * properties exactly as received; unlike known variants, those keys * bypass lenient-field salvage and arrive unvalidated. diff --git a/src/v2/acp.ts b/src/v2/acp.ts index 8b75d557..8cebdb1d 100644 --- a/src/v2/acp.ts +++ b/src/v2/acp.ts @@ -2484,7 +2484,7 @@ const clientRequestSpecs = { validate.zDisconnectMcpResponse, emptyObjectResponse, ), - unstable_createElicitation: requestSpec< + createElicitation: requestSpec< schema.CreateElicitationRequest, schema.CreateElicitationResponse >( @@ -2503,11 +2503,10 @@ const clientNotificationSpecs = { schema.CLIENT_METHODS.mcp_message, validate.zMessageMcpNotification, ), - unstable_completeElicitation: - notificationSpec( - schema.CLIENT_METHODS.elicitation_complete, - validate.zCompleteElicitationNotification, - ), + completeElicitation: notificationSpec( + schema.CLIENT_METHODS.elicitation_complete, + validate.zCompleteElicitationNotification, + ), }; const agentRequestSpecsByMethod = specsByMethod(agentRequestSpecs); diff --git a/src/v2/schema/guards.gen.ts b/src/v2/schema/guards.gen.ts index f405c946..098062a8 100644 --- a/src/v2/schema/guards.gen.ts +++ b/src/v2/schema/guards.gen.ts @@ -83,9 +83,6 @@ const zGuardMultiSelectItemsString = validate.zStringMultiSelectItems.and( z.object({ type: z.literal("string") }), ); const zGuardMultiSelectItemsTitled = validate.zTitledMultiSelectItems; -const zGuardAuthMethodEnvVar = validate.zAuthMethodEnvVar.and( - z.object({ type: z.literal("env_var") }), -); const zGuardAuthMethodTerminal = validate.zAuthMethodTerminal.and( z.object({ type: z.literal("terminal") }), ); @@ -176,6 +173,13 @@ const zGuardSessionUpdateSessionInfoUpdate = validate.zSessionInfoUpdate.and( const zGuardSessionUpdateUsageUpdate = validate.zUsageUpdate.and( z.object({ sessionUpdate: z.literal("usage_update") }), ); +const zGuardSessionUpdateCompactionUpdate = validate.zCompactionUpdate.and( + z.object({ sessionUpdate: z.literal("compaction_update") }), +); +const zGuardSessionUpdateCompactionSummaryChunk = + validate.zCompactionSummaryChunk.and( + z.object({ sessionUpdate: z.literal("compaction_summary_chunk") }), + ); const zGuardStateUpdateRunning = validate.zRunningStateUpdate.and( z.object({ state: z.literal("running") }), ); @@ -581,17 +585,11 @@ export const DiffChange = { } as const; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Request from the agent to elicit structured user input. * * The agent sends this to the client to request information from the user, * either via a form or by directing them to a URL. * Elicitations are tied to a session (optionally a tool call) or a request. - * - * @experimental */ export type CreateElicitationRequest = types.CreateElicitationRequest; /** @@ -608,8 +606,6 @@ export type CreateElicitationRequest = types.CreateElicitationRequest; * another variant's payload) guards are conservative where wire parsing * may still accept the value — narrow wire-parsed values when exact * parity matters. - * - * @experimental */ export const CreateElicitationRequest = { /** Narrow to the `form` variant, validating its payload. */ @@ -825,16 +821,6 @@ export type AuthMethod = types.AuthMethod; * parity matters. */ export const AuthMethod = { - /** Narrow to the `env_var` variant, validating its payload. */ - isEnvVar( - value: types.AuthMethod, - ): value is types.AuthMethodEnvVar & { type: "env_var" } { - return ( - tagOf(value, "type") === "env_var" && - zGuardAuthMethodEnvVar.safeParse(value).success - ); - }, - /** Narrow to the `terminal` variant, validating its payload. */ isTerminal( value: types.AuthMethod, @@ -872,7 +858,7 @@ export const AuthMethod = { const tag = tagOf(value, "type"); return ( typeof tag === "string" && - !["agent", "env_var", "terminal"].includes(tag) && + !["agent", "terminal"].includes(tag) && zGuardAuthMethodCustom.safeParse(value).success ); }, @@ -1236,6 +1222,28 @@ export const SessionUpdate = { ); }, + /** Narrow to the `compaction_update` variant, validating its payload. */ + isCompactionUpdate( + value: types.SessionUpdate, + ): value is types.CompactionUpdate & { sessionUpdate: "compaction_update" } { + return ( + tagOf(value, "sessionUpdate") === "compaction_update" && + zGuardSessionUpdateCompactionUpdate.safeParse(value).success + ); + }, + + /** Narrow to the `compaction_summary_chunk` variant, validating its payload. */ + isCompactionSummaryChunk( + value: types.SessionUpdate, + ): value is types.CompactionSummaryChunk & { + sessionUpdate: "compaction_summary_chunk"; + } { + return ( + tagOf(value, "sessionUpdate") === "compaction_summary_chunk" && + zGuardSessionUpdateCompactionSummaryChunk.safeParse(value).success + ); + }, + /** * Narrow to a custom or future variant: the `sessionUpdate` tag matches no known variant. * @@ -1255,6 +1263,8 @@ export const SessionUpdate = { "agent_thought", "agent_thought_chunk", "available_commands_update", + "compaction_summary_chunk", + "compaction_update", "config_option_update", "plan_removed", "plan_update", @@ -1702,13 +1712,7 @@ export const RequestPermissionOutcome = { } as const; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Response from the client to an elicitation request. - * - * @experimental */ export type CreateElicitationResponse = types.CreateElicitationResponse; /** @@ -1725,8 +1729,6 @@ export type CreateElicitationResponse = types.CreateElicitationResponse; * another variant's payload) guards are conservative where wire parsing * may still accept the value — narrow wire-parsed values when exact * parity matters. - * - * @experimental */ export const CreateElicitationResponse = { /** Narrow to the `accept` variant, validating its payload. */ diff --git a/src/v2/schema/index.ts b/src/v2/schema/index.ts index b4904524..0b91855c 100644 --- a/src/v2/schema/index.ts +++ b/src/v2/schema/index.ts @@ -13,10 +13,8 @@ export type { Annotations, AudioContent, AuthCapabilities, - AuthEnvVar, AuthMethod, AuthMethodAgent, - AuthMethodEnvVar, AuthMethodId, AuthMethodTerminal, AvailableCommand, @@ -36,6 +34,10 @@ export type { CloseSessionRequest, CloseSessionResponse, CommandPermissionSubject, + CompactionId, + CompactionStatus, + CompactionSummaryChunk, + CompactionUpdate, CompleteElicitationNotification, ConfigOptionUpdate, ConnectMcpRequest, diff --git a/src/v2/schema/types.gen.ts b/src/v2/schema/types.gen.ts index 8183a1e6..24fff294 100644 --- a/src/v2/schema/types.gen.ts +++ b/src/v2/schema/types.gen.ts @@ -911,17 +911,11 @@ export type PermissionOptionKind = "allow_once" | "allow_always" | "reject_once" | "reject_always" | string; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Request from the agent to elicit structured user input. * * The agent sends this to the client to request information from the user, * either via a form or by directing them to a URL. * Elicitations are tied to a session (optionally a tool call) or a request. - * - * @experimental */ export type CreateElicitationRequest = ( | (ElicitationFormMode & { @@ -951,6 +945,8 @@ export type CreateElicitationRequest = ( * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) */ _meta?: { @@ -959,17 +955,11 @@ export type CreateElicitationRequest = ( }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Session-scoped elicitation, optionally tied to a specific tool call. * * When `tool_call_id` is set, the elicitation is tied to a specific tool call. * This is useful when an agent receives an elicitation from an MCP server * during a tool call and needs to redirect it to the user. - * - * @experimental */ export type ElicitationSessionScope = { /** @@ -978,19 +968,16 @@ export type ElicitationSessionScope = { sessionId: SessionId; /** * Optional tool call within the session. + * + * Optional. Omitted and `null` are equivalent and mean the elicitation is scoped to the + * session without a specific tool call. */ toolCallId?: ToolCallId | null; }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Request-scoped elicitation, tied to a specific JSON-RPC request outside of a session * (e.g., during auth/configuration phases before any session is started). - * - * @experimental */ export type ElicitationRequestScope = { /** @@ -1012,6 +999,8 @@ export type ElicitationSchema = { type?: ElicitationSchemaType; /** * Optional title for the schema. + * + * Optional. Omitted and `null` are equivalent and mean no title is provided. */ title?: string | null; /** @@ -1022,10 +1011,14 @@ export type ElicitationSchema = { }; /** * List of required property names. + * + * Optional. Omitted and `null` are equivalent and mean no property names are required. */ required?: Array | null; /** * Optional description of what this schema represents. + * + * Optional. Omitted and `null` are equivalent and mean no schema description is provided. */ description?: string | null; /** @@ -1033,6 +1026,8 @@ export type ElicitationSchema = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) */ _meta?: { @@ -1099,6 +1094,8 @@ export type EnumOption = { title: string; /** * Human-readable description. + * + * Optional. Omitted and `null` are equivalent and mean no description is provided. */ description?: string | null; /** @@ -1106,6 +1103,8 @@ export type EnumOption = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) */ _meta?: { @@ -1122,40 +1121,58 @@ export type EnumOption = { export type StringPropertySchema = { /** * Optional title for the property. + * + * Optional. Omitted and `null` are equivalent and mean no title is provided. */ title?: string | null; /** * Human-readable description. + * + * Optional. Omitted and `null` are equivalent and mean no description is provided. */ description?: string | null; /** * Minimum string length. + * + * Optional. Omitted and `null` are equivalent and mean there is no minimum length constraint. */ minLength?: number | null; /** * Maximum string length. + * + * Optional. Omitted and `null` are equivalent and mean there is no maximum length constraint. */ maxLength?: number | null; /** * Pattern the string must match. + * + * Optional. Omitted and `null` are equivalent and mean there is no pattern constraint. */ pattern?: string | null; /** * String format. + * + * Optional. Omitted and `null` are equivalent and mean there is no format constraint. */ format?: StringFormat | null; /** * Default value. + * + * Optional. Omitted and `null` are equivalent and mean no default value is provided. */ default?: string | null; /** * Enum values for untitled single-select enums. * Must contain at least one value when present. + * Optional. Omitted and `null` are equivalent and mean no untitled single-select choices are + * declared by `enum`. */ enum?: Array | null; /** * Titled enum options for titled single-select enums. * Must contain at least one option when present. + * Optional. Omitted and `null` are equivalent and mean no titled single-select choices are + * declared by `oneOf`. */ oneOf?: Array | null; /** @@ -1163,6 +1180,8 @@ export type StringPropertySchema = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) */ _meta?: { @@ -1176,22 +1195,32 @@ export type StringPropertySchema = { export type NumberPropertySchema = { /** * Optional title for the property. + * + * Optional. Omitted and `null` are equivalent and mean no title is provided. */ title?: string | null; /** * Human-readable description. + * + * Optional. Omitted and `null` are equivalent and mean no description is provided. */ description?: string | null; /** * Minimum value (inclusive). + * + * Optional. Omitted and `null` are equivalent and mean there is no inclusive lower bound. */ minimum?: number | null; /** * Maximum value (inclusive). + * + * Optional. Omitted and `null` are equivalent and mean there is no inclusive upper bound. */ maximum?: number | null; /** * Default value. + * + * Optional. Omitted and `null` are equivalent and mean no default value is provided. */ default?: number | null; /** @@ -1199,6 +1228,8 @@ export type NumberPropertySchema = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) */ _meta?: { @@ -1212,22 +1243,32 @@ export type NumberPropertySchema = { export type IntegerPropertySchema = { /** * Optional title for the property. + * + * Optional. Omitted and `null` are equivalent and mean no title is provided. */ title?: string | null; /** * Human-readable description. + * + * Optional. Omitted and `null` are equivalent and mean no description is provided. */ description?: string | null; /** * Minimum value (inclusive). + * + * Optional. Omitted and `null` are equivalent and mean there is no inclusive lower bound. */ minimum?: number | null; /** * Maximum value (inclusive). + * + * Optional. Omitted and `null` are equivalent and mean there is no inclusive upper bound. */ maximum?: number | null; /** * Default value. + * + * Optional. Omitted and `null` are equivalent and mean no default value is provided. */ default?: number | null; /** @@ -1235,6 +1276,8 @@ export type IntegerPropertySchema = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) */ _meta?: { @@ -1248,14 +1291,20 @@ export type IntegerPropertySchema = { export type BooleanPropertySchema = { /** * Optional title for the property. + * + * Optional. Omitted and `null` are equivalent and mean no title is provided. */ title?: string | null; /** * Human-readable description. + * + * Optional. Omitted and `null` are equivalent and mean no description is provided. */ description?: string | null; /** * Default value. + * + * Optional. Omitted and `null` are equivalent and mean no default value is provided. */ default?: boolean | null; /** @@ -1263,6 +1312,8 @@ export type BooleanPropertySchema = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) */ _meta?: { @@ -1303,6 +1354,8 @@ export type StringMultiSelectItems = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) */ _meta?: { @@ -1323,6 +1376,8 @@ export type TitledMultiSelectItems = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) */ _meta?: { @@ -1336,18 +1391,26 @@ export type TitledMultiSelectItems = { export type MultiSelectPropertySchema = { /** * Optional title for the property. + * + * Optional. Omitted and `null` are equivalent and mean no title is provided. */ title?: string | null; /** * Human-readable description. + * + * Optional. Omitted and `null` are equivalent and mean no description is provided. */ description?: string | null; /** * Minimum number of items to select. + * + * Optional. Omitted and `null` are equivalent and mean there is no minimum selection count. */ minItems?: number | null; /** * Maximum number of items to select. + * + * Optional. Omitted and `null` are equivalent and mean there is no maximum selection count. */ maxItems?: number | null; /** @@ -1356,6 +1419,8 @@ export type MultiSelectPropertySchema = { items: MultiSelectItems; /** * Default selected values. + * + * Optional. Omitted and `null` are equivalent and mean no default selections are provided. */ default?: Array | null; /** @@ -1363,6 +1428,8 @@ export type MultiSelectPropertySchema = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) */ _meta?: { @@ -1371,13 +1438,7 @@ export type MultiSelectPropertySchema = { }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Form-based elicitation mode where the client renders a form from the provided schema. - * - * @experimental */ export type ElicitationFormMode = ( ElicitationSessionScope | ElicitationRequestScope @@ -1389,24 +1450,12 @@ export type ElicitationFormMode = ( }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Unique identifier for an elicitation. - * - * @experimental */ export type ElicitationId = string; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * URL-based elicitation mode where the client directs the user to a URL. - * - * @experimental */ export type ElicitationUrlMode = ( ElicitationSessionScope | ElicitationRequestScope @@ -2471,9 +2520,6 @@ export type PositionEncodingKind = "utf-16" | "utf-32" | "utf-8"; * The `type` field acts as the discriminator in the serialized JSON form. */ export type AuthMethod = - | (AuthMethodEnvVar & { - type: "env_var"; - }) | (AuthMethodTerminal & { type: "terminal"; }) @@ -2520,94 +2566,7 @@ export type AuthMethod = export type AuthMethodId = string; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * - * Describes a single environment variable for an [`AuthMethodEnvVar`] authentication method. - * - * @experimental - */ -export type AuthEnvVar = { - /** - * The environment variable name (e.g. `"OPENAI_API_KEY"`). - */ - name: string; - /** - * Human-readable label for this variable, displayed in client UI. - */ - label?: string | null; - /** - * Whether this value is a secret (e.g. API key, token). - * Clients should use a password-style input for secret vars. - * - * Defaults to `true`. - */ - secret?: boolean; - /** - * Whether this variable is optional. - * - * Defaults to `false`. - */ - optional?: boolean; - /** - * The _meta property is reserved by ACP to allow clients and agents to attach additional - * metadata to their interactions. Implementations MUST NOT make assumptions about values at - * these keys. - * - * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) - */ - _meta?: { - [key: string]: unknown; - } | null; -}; - -/** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * - * Environment variable authentication method. - * - * The user provides credentials that the client passes to the agent as environment variables. - * - * @experimental - */ -export type AuthMethodEnvVar = { - /** - * Unique identifier for this authentication method. - */ - methodId: AuthMethodId; - /** - * Human-readable name of the authentication method. - */ - name: string; - /** - * Optional description providing more details about this authentication method. - */ - description?: string | null; - /** - * The environment variables the client should set. - */ - vars: Array; - /** - * Optional link to a page where the user can obtain their credentials. - */ - link?: string | null; - /** - * The _meta property is reserved by ACP to allow clients and agents to attach additional - * metadata to their interactions. Implementations MUST NOT make assumptions about values at - * these keys. - * - * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) - */ - _meta?: { - [key: string]: unknown; - } | null; -}; - -/** - * An environment variable to set when launching an MCP server. + * An environment variable to set when launching a process. */ export type EnvVariable = { /** @@ -2631,15 +2590,13 @@ export type EnvVariable = { }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Terminal-based authentication method. * - * The client runs an interactive terminal for the user to authenticate via a TUI. - * - * @experimental + * The client runs the configured agent program as a separate interactive + * process for the user to authenticate via a TUI. Agents MUST advertise this + * method only when the client enabled its terminal authentication capability. + * A zero exit status signals success; any other termination signals failure. + * The client MUST NOT pass this method to `auth/login`. */ export type AuthMethodTerminal = { /** @@ -2655,11 +2612,13 @@ export type AuthMethodTerminal = { */ description?: string | null; /** - * Additional arguments to pass when running the agent binary for terminal auth. + * Additional arguments to append to the configured agent invocation for terminal auth. */ args?: Array; /** - * Additional environment variables to set when running the agent binary for terminal auth. + * Additional environment variables to set on the configured agent invocation for terminal auth. + * Names MUST be unique. These values override same-named variables in the + * base launch configuration. */ env?: Array; /** @@ -2675,7 +2634,7 @@ export type AuthMethodTerminal = { }; /** - * Agent handles authentication itself. + * Agent handles authentication itself through `auth/login`. * * The `type` discriminator value is `agent`. */ @@ -3762,6 +3721,12 @@ export type SessionUpdate = | (UsageUpdate & { sessionUpdate: "usage_update"; }) + | (CompactionUpdate & { + sessionUpdate: "compaction_update"; + }) + | (CompactionSummaryChunk & { + sessionUpdate: "compaction_summary_chunk"; + }) | { /** * Custom or future session update type. @@ -4629,10 +4594,95 @@ export type UsageUpdate = { * * This capability is not part of the spec yet, and may be removed or changed at any point. * - * Notification sent by the agent when a URL-based elicitation is complete. + * Unique identifier for a context compaction within a session. + * + * @experimental + */ +export type CompactionId = string; + +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Lifecycle state of a context compaction. + * + * @experimental + */ +export type CompactionStatus = + "in_progress" | "completed" | "failed" | "cancelled" | string; + +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * A context compaction upsert. The first update fixes the compaction's + * timeline position. Later updates with the same ID patch that entity in place. + * + * `summary`, `error`, and `_meta` have patch semantics: omission leaves the + * stored value unchanged, `null` clears it, and a concrete value replaces it. + * `summary: []` also clears the retained summary. A non-empty summary is only + * valid with `completed`; `error` is only valid with `failed`. + * + * @experimental + */ +export type CompactionUpdate = { + /** + * The Agent-owned ID of this compaction, unique within the session. + */ + compactionId: CompactionId; + /** + * Current lifecycle status. + */ + status: CompactionStatus; + /** + * Complete replacement user-displayable summary retained by the compaction. + */ + summary?: Array | null; + /** + * Human-readable description of why the compaction failed. + */ + error?: string | null; + /** + * Extensible metadata patch for this compaction. + */ + _meta?: { + [key: string]: unknown; + } | null; +}; + +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * A content block appended to the retained summary of an in-progress + * compaction. Agents send chunks only after an `in_progress` update and before + * the terminal update for the same ID. * * @experimental */ +export type CompactionSummaryChunk = { + /** + * ID of the compaction whose summary receives this content. + */ + compactionId: CompactionId; + /** + * One content block to append. + */ + content: ContentBlock; + /** + * Metadata scoped to this chunk. Omission and `null` both mean absent. + */ + _meta?: { + [key: string]: unknown; + } | null; +}; + +/** + * Notification sent by the agent when a URL-based elicitation is complete. + */ export type CompleteElicitationNotification = { /** * The ID of the elicitation that completed. @@ -4643,6 +4693,8 @@ export type CompleteElicitationNotification = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) */ _meta?: { @@ -4780,32 +4832,20 @@ export type InitializeRequest = { */ export type ClientCapabilities = { /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Authentication capabilities supported by the client. * Determines which authentication method types the agent may include * in its `InitializeResponse`. * * Optional. Omitted or `null` both mean the client does not advertise any * authentication-method extensions. - * - * @experimental */ auth?: AuthCapabilities | null; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Elicitation capabilities supported by the client. * Determines which elicitation modes the agent may use. * * Optional. Omitted or `null` both mean the client does not advertise * elicitation support. - * - * @experimental */ elicitation?: ElicitationCapabilities | null; /** @@ -4844,24 +4884,20 @@ export type ClientCapabilities = { }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Authentication capabilities supported by the client. * * Advertised during initialization to inform the agent which authentication * method types the client can handle. This governs opt-in types that require * additional client-side support. - * - * @experimental */ export type AuthCapabilities = { /** * Whether the client supports `terminal` authentication methods. * * Optional. Omitted or `null` both mean the client does not advertise support. - * Supplying `{}` means the agent may include `terminal` entries in its authentication methods. + * 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. */ terminal?: TerminalAuthCapabilities | null; /** @@ -4877,15 +4913,11 @@ export type AuthCapabilities = { }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Capabilities for terminal authentication methods. * - * Supplying `{}` means the client supports terminal authentication methods. - * - * @experimental + * Supplying `{}` means the client can reproduce the configured agent + * invocation in an interactive terminal and supports terminal authentication + * methods. */ export type TerminalAuthCapabilities = { /** @@ -4901,20 +4933,14 @@ export type TerminalAuthCapabilities = { }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Elicitation capabilities supported by the client. - * - * @experimental */ export type ElicitationCapabilities = { /** * Whether the client supports form-based elicitation. * - * Optional. Omitted or `null` both mean the client does not advertise support. - * Supplying `{}` means the client supports form-based elicitation. + * Optional. Omitted and `null` are equivalent and mean form support is not advertised. + * Supplying `{}` explicitly advertises form support. */ form?: ElicitationFormCapabilities | null; /** @@ -4929,6 +4955,8 @@ export type ElicitationCapabilities = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) */ _meta?: { @@ -4937,15 +4965,9 @@ export type ElicitationCapabilities = { }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Form-based elicitation capabilities. * * Supplying `{}` means the client supports form-based elicitation. - * - * @experimental */ export type ElicitationFormCapabilities = { /** @@ -4953,6 +4975,8 @@ export type ElicitationFormCapabilities = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) */ _meta?: { @@ -4961,15 +4985,9 @@ export type ElicitationFormCapabilities = { }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * URL-based elicitation capabilities. * * Supplying `{}` means the client supports URL-based elicitation. - * - * @experimental */ export type ElicitationUrlCapabilities = { /** @@ -4977,6 +4995,8 @@ export type ElicitationUrlCapabilities = { * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) */ _meta?: { @@ -6184,13 +6204,7 @@ export type SelectedPermissionOutcome = { }; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Response from the client to an elicitation request. - * - * @experimental */ export type CreateElicitationResponse = ( | (ElicitationAcceptAction & { @@ -6219,6 +6233,8 @@ export type CreateElicitationResponse = ( * metadata to their interactions. Implementations MUST NOT make assumptions about values at * these keys. * + * Optional. Omitted and `null` are equivalent and mean no metadata. + * * See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) */ _meta?: { @@ -6233,13 +6249,7 @@ export type ElicitationContentValue = string | number | number | boolean | Array; /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * The user accepted the elicitation and provided content. - * - * @experimental */ export type ElicitationAcceptAction = { /** diff --git a/src/v2/schema/zod.gen.ts b/src/v2/schema/zod.gen.ts index 00ae9dbd..f0c3a8f1 100644 --- a/src/v2/schema/zod.gen.ts +++ b/src/v2/schema/zod.gen.ts @@ -646,17 +646,11 @@ export const zRequestPermissionRequest = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Session-scoped elicitation, optionally tied to a specific tool call. * * When `tool_call_id` is set, the elicitation is tied to a specific tool call. * This is useful when an agent receives an elicitation from an MCP server * during a tool call and needs to redirect it to the user. - * - * @experimental */ export const zElicitationSessionScope = z.object({ sessionId: zSessionId, @@ -664,14 +658,8 @@ export const zElicitationSessionScope = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Request-scoped elicitation, tied to a specific JSON-RPC request outside of a session * (e.g., during auth/configuration phases before any session is started). - * - * @experimental */ export const zElicitationRequestScope = z.object({ requestId: zRequestId, @@ -923,13 +911,7 @@ export const zElicitationSchema = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Form-based elicitation mode where the client renders a form from the provided schema. - * - * @experimental */ export const zElicitationFormMode = z.intersection( z.union([zElicitationSessionScope, zElicitationRequestScope]), @@ -939,24 +921,12 @@ export const zElicitationFormMode = z.intersection( ); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Unique identifier for an elicitation. - * - * @experimental */ export const zElicitationId = z.string(); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * URL-based elicitation mode where the client directs the user to a URL. - * - * @experimental */ export const zElicitationUrlMode = z.intersection( z.union([zElicitationSessionScope, zElicitationRequestScope]), @@ -967,18 +937,12 @@ export const zElicitationUrlMode = z.intersection( ); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Request from the agent to elicit structured user input. * * The agent sends this to the client to request information from the user, * either via a form or by directing them to a URL. * Elicitations are tied to a session (optionally a tool call) or a request. * - * @experimental - * * Custom variants (unknown `mode` values) keep their extra * properties exactly as received; unlike known variants, those keys * bypass lenient-field salvage and arrive unvalidated. @@ -1653,56 +1617,7 @@ export const zAgentCapabilities = z.object({ export const zAuthMethodId = z.string(); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * - * Describes a single environment variable for an [`AuthMethodEnvVar`] authentication method. - * - * @experimental - */ -export const zAuthEnvVar = z.object({ - name: z.string(), - label: defaultOnError(z.string().nullish(), () => undefined), - secret: defaultOnError( - z.boolean().optional().default(true), - () => true as const, - ), - optional: defaultOnError( - z.boolean().optional().default(false), - () => false as const, - ), - _meta: defaultOnError( - z.record(z.string(), z.unknown()).nullish(), - () => undefined, - ), -}); - -/** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * - * Environment variable authentication method. - * - * The user provides credentials that the client passes to the agent as environment variables. - * - * @experimental - */ -export const zAuthMethodEnvVar = z.object({ - methodId: zAuthMethodId, - name: z.string(), - description: defaultOnError(z.string().nullish(), () => undefined), - vars: requiredDefaultOnError(vecSkipError(zAuthEnvVar), () => []), - link: defaultOnError(z.url().nullish(), () => undefined), - _meta: defaultOnError( - z.record(z.string(), z.unknown()).nullish(), - () => undefined, - ), -}); - -/** - * An environment variable to set when launching an MCP server. + * An environment variable to set when launching a process. */ export const zEnvVariable = z.object({ name: z.string(), @@ -1714,15 +1629,13 @@ export const zEnvVariable = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Terminal-based authentication method. * - * The client runs an interactive terminal for the user to authenticate via a TUI. - * - * @experimental + * The client runs the configured agent program as a separate interactive + * process for the user to authenticate via a TUI. Agents MUST advertise this + * method only when the client enabled its terminal authentication capability. + * A zero exit status signals success; any other termination signals failure. + * The client MUST NOT pass this method to `auth/login`. */ export const zAuthMethodTerminal = z.object({ methodId: zAuthMethodId, @@ -1737,7 +1650,7 @@ export const zAuthMethodTerminal = z.object({ }); /** - * Agent handles authentication itself. + * Agent handles authentication itself through `auth/login`. * * The `type` discriminator value is `agent`. */ @@ -1762,11 +1675,6 @@ export const zAuthMethodAgent = z.object({ */ export const zAuthMethod = preserveCustomPayload( z.union([ - zAuthMethodEnvVar.and( - z.object({ - type: z.literal("env_var"), - }), - ), zAuthMethodTerminal.and( z.object({ type: z.literal("terminal"), @@ -1789,11 +1697,11 @@ export const zAuthMethod = preserveCustomPayload( ), }), "type", - ["agent", "env_var", "terminal"], + ["agent", "terminal"], ), ]), "type", - ["agent", "env_var", "terminal"], + ["agent", "terminal"], ); /** @@ -3083,6 +2991,83 @@ export const zUsageUpdate = z.object({ ), }); +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Unique identifier for a context compaction within a session. + * + * @experimental + */ +export const zCompactionId = z.string(); + +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Lifecycle state of a context compaction. + * + * @experimental + */ +export const zCompactionStatus = z.union([ + z.literal("in_progress"), + z.literal("completed"), + z.literal("failed"), + z.literal("cancelled"), + z.string(), +]); + +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * A context compaction upsert. The first update fixes the compaction's + * timeline position. Later updates with the same ID patch that entity in place. + * + * `summary`, `error`, and `_meta` have patch semantics: omission leaves the + * stored value unchanged, `null` clears it, and a concrete value replaces it. + * `summary: []` also clears the retained summary. A non-empty summary is only + * valid with `completed`; `error` is only valid with `failed`. + * + * @experimental + */ +export const zCompactionUpdate = z.object({ + compactionId: zCompactionId, + status: zCompactionStatus, + summary: defaultOnError( + vecSkipError(zContentBlock).nullish(), + () => undefined, + ), + error: defaultOnError(z.string().nullish(), () => undefined), + _meta: defaultOnError( + z.record(z.string(), z.unknown()).nullish(), + () => undefined, + ), +}); + +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * A content block appended to the retained summary of an in-progress + * compaction. Agents send chunks only after an `in_progress` update and before + * the terminal update for the same ID. + * + * @experimental + */ +export const zCompactionSummaryChunk = z.object({ + compactionId: zCompactionId, + content: zContentBlock, + _meta: defaultOnError( + z.record(z.string(), z.unknown()).nullish(), + () => undefined, + ), +}); + /** * Different types of updates that can be sent while a session exists. * @@ -3181,6 +3166,16 @@ export const zSessionUpdate = preserveCustomPayload( sessionUpdate: z.literal("usage_update"), }), ), + zCompactionUpdate.and( + z.object({ + sessionUpdate: z.literal("compaction_update"), + }), + ), + zCompactionSummaryChunk.and( + z.object({ + sessionUpdate: z.literal("compaction_summary_chunk"), + }), + ), excludeKnownTags( z.object({ sessionUpdate: z.string(), @@ -3192,6 +3187,8 @@ export const zSessionUpdate = preserveCustomPayload( "agent_thought", "agent_thought_chunk", "available_commands_update", + "compaction_summary_chunk", + "compaction_update", "config_option_update", "plan_removed", "plan_update", @@ -3214,6 +3211,8 @@ export const zSessionUpdate = preserveCustomPayload( "agent_thought", "agent_thought_chunk", "available_commands_update", + "compaction_summary_chunk", + "compaction_update", "config_option_update", "plan_removed", "plan_update", @@ -3246,13 +3245,7 @@ export const zUpdateSessionNotification = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Notification sent by the agent when a URL-based elicitation is complete. - * - * @experimental */ export const zCompleteElicitationNotification = z.object({ elicitationId: zElicitationId, @@ -3312,15 +3305,11 @@ export const zAgentNotification = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Capabilities for terminal authentication methods. * - * Supplying `{}` means the client supports terminal authentication methods. - * - * @experimental + * Supplying `{}` means the client can reproduce the configured agent + * invocation in an interactive terminal and supports terminal authentication + * methods. */ export const zTerminalAuthCapabilities = z.object({ _meta: defaultOnError( @@ -3330,17 +3319,11 @@ export const zTerminalAuthCapabilities = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Authentication capabilities supported by the client. * * Advertised during initialization to inform the agent which authentication * method types the client can handle. This governs opt-in types that require * additional client-side support. - * - * @experimental */ export const zAuthCapabilities = z.object({ terminal: defaultOnError( @@ -3354,15 +3337,9 @@ export const zAuthCapabilities = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Form-based elicitation capabilities. * * Supplying `{}` means the client supports form-based elicitation. - * - * @experimental */ export const zElicitationFormCapabilities = z.object({ _meta: defaultOnError( @@ -3372,15 +3349,9 @@ export const zElicitationFormCapabilities = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * URL-based elicitation capabilities. * * Supplying `{}` means the client supports URL-based elicitation. - * - * @experimental */ export const zElicitationUrlCapabilities = z.object({ _meta: defaultOnError( @@ -3390,13 +3361,7 @@ export const zElicitationUrlCapabilities = z.object({ }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Elicitation capabilities supported by the client. - * - * @experimental */ export const zElicitationCapabilities = z.object({ form: defaultOnError(zElicitationFormCapabilities.nullish(), () => undefined), @@ -4188,27 +4153,15 @@ export const zElicitationContentValue = z.union([ ]); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * The user accepted the elicitation and provided content. - * - * @experimental */ export const zElicitationAcceptAction = z.object({ content: z.record(z.string(), zElicitationContentValue).nullish(), }); /** - * **UNSTABLE** - * - * This capability is not part of the spec yet, and may be removed or changed at any point. - * * Response from the client to an elicitation request. * - * @experimental - * * Custom variants (unknown `action` values) keep their extra * properties exactly as received; unlike known variants, those keys * bypass lenient-field salvage and arrive unvalidated.