From e5fdc900caf52a4807f7bcc43707a2e2b493a178 Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Thu, 5 Mar 2026 15:39:27 +0100 Subject: [PATCH] feat: Update to 0.11.0 of the schema --- schema/meta.json | 3 +- schema/schema.json | 299 +++++++++++++++++++++++++++++++-- scripts/generate.js | 2 +- src/acp.ts | 9 +- src/schema/index.ts | 15 +- src/schema/types.gen.ts | 364 ++++++++++++++++++++++++++++++++++++++-- src/schema/zod.gen.ts | 174 +++++++++++++++++-- 7 files changed, 822 insertions(+), 44 deletions(-) diff --git a/schema/meta.json b/schema/meta.json index 507c21d7..b1cba085 100644 --- a/schema/meta.json +++ b/schema/meta.json @@ -11,7 +11,8 @@ "session_resume": "session/resume", "session_set_config_option": "session/set_config_option", "session_set_mode": "session/set_mode", - "session_set_model": "session/set_model" + "session_set_model": "session/set_model", + "session_stop": "session/stop" }, "clientMethods": { "fs_read_text_file": "fs/read_text_file", diff --git a/schema/schema.json b/schema/schema.json index f6bed4ae..64cba0d3 100644 --- a/schema/schema.json +++ b/schema/schema.json @@ -167,11 +167,11 @@ { "allOf": [ { - "$ref": "#/$defs/KillTerminalCommandRequest" + "$ref": "#/$defs/KillTerminalRequest" } ], - "description": "Kills the terminal command without releasing the terminal\n\nWhile `terminal/release` will also kill the command, this method will keep\nthe `TerminalId` valid so it can be used with other methods.\n\nThis method can be helpful when implementing command timeouts which terminate\nthe command as soon as elapsed, and then get the final output so it can be sent\nto the model.\n\nNote: `terminal/release` when `TerminalId` is no longer needed.\n\nSee protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)", - "title": "KillTerminalCommandRequest" + "description": "Kills the terminal command without releasing the terminal\n\nWhile `terminal/release` will also kill the command, this method will keep\nthe `TerminalId` valid so it can be used with other methods.\n\nThis method can be helpful when implementing command timeouts which terminate\nthe command as soon as elapsed, and then get the final output so it can be sent\nto the model.\n\nNote: Call `terminal/release` when `TerminalId` is no longer needed.\n\nSee protocol docs: [Terminals](https://agentclientprotocol.com/protocol/terminals)", + "title": "KillTerminalRequest" }, { "allOf": [ @@ -260,6 +260,14 @@ ], "title": "ResumeSessionResponse" }, + { + "allOf": [ + { + "$ref": "#/$defs/StopSessionResponse" + } + ], + "title": "StopSessionResponse" + }, { "allOf": [ { @@ -376,8 +384,100 @@ "required": ["data", "mimeType"], "type": "object" }, + "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.", + "properties": { + "_meta": { + "additionalProperties": true, + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "type": ["object", "null"] + }, + "terminal": { + "default": false, + "description": "Whether the client supports `terminal` authentication methods.\n\nWhen `true`, the agent may include `terminal` entries in its authentication methods.", + "type": "boolean" + } + }, + "type": "object" + }, + "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.", + "properties": { + "_meta": { + "additionalProperties": true, + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "type": ["object", "null"] + }, + "label": { + "description": "Human-readable label for this variable, displayed in client UI.", + "type": ["string", "null"] + }, + "name": { + "description": "The environment variable name (e.g. `\"OPENAI_API_KEY\"`).", + "type": "string" + }, + "optional": { + "default": false, + "description": "Whether this variable is optional.\n\nDefaults to `false`.", + "type": "boolean" + }, + "secret": { + "default": true, + "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" + } + }, + "required": ["name"], + "type": "object" + }, "AuthMethod": { - "description": "Describes an available authentication method.", + "anyOf": [ + { + "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\nUser provides a key that the client passes to the agent as an environment variable.", + "properties": { + "type": { + "const": "env_var", + "type": "string" + } + }, + "required": ["type"], + "type": "object" + }, + { + "allOf": [ + { + "$ref": "#/$defs/AuthMethodTerminal" + } + ], + "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.", + "properties": { + "type": { + "const": "terminal", + "type": "string" + } + }, + "required": ["type"], + "type": "object" + }, + { + "allOf": [ + { + "$ref": "#/$defs/AuthMethodAgent" + } + ], + "description": "Agent handles authentication itself.\n\nThis is the default when no `type` is specified.", + "title": "agent" + } + ], + "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`." + }, + "AuthMethodAgent": { + "description": "Agent handles authentication itself.\n\nThis is the default authentication method type.", "properties": { "_meta": { "additionalProperties": true, @@ -400,6 +500,79 @@ "required": ["id", "name"], "type": "object" }, + "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.", + "properties": { + "_meta": { + "additionalProperties": true, + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "type": ["object", "null"] + }, + "description": { + "description": "Optional description providing more details about this authentication method.", + "type": ["string", "null"] + }, + "id": { + "description": "Unique identifier for this authentication method.", + "type": "string" + }, + "link": { + "description": "Optional link to a page where the user can obtain their credentials.", + "type": ["string", "null"] + }, + "name": { + "description": "Human-readable name of the authentication method.", + "type": "string" + }, + "vars": { + "description": "The environment variables the client should set.", + "items": { + "$ref": "#/$defs/AuthEnvVar" + }, + "type": "array" + } + }, + "required": ["id", "name", "vars"], + "type": "object" + }, + "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.", + "properties": { + "_meta": { + "additionalProperties": true, + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "type": ["object", "null"] + }, + "args": { + "description": "Additional arguments to pass when running the agent binary for terminal auth.", + "items": { + "type": "string" + }, + "type": "array" + }, + "description": { + "description": "Optional description providing more details about this authentication method.", + "type": ["string", "null"] + }, + "env": { + "additionalProperties": { + "type": "string" + }, + "description": "Additional environment variables to set when running the agent binary for terminal auth.", + "type": "object" + }, + "id": { + "description": "Unique identifier for this authentication method.", + "type": "string" + }, + "name": { + "description": "Human-readable name of the authentication method.", + "type": "string" + } + }, + "required": ["id", "name"], + "type": "object" + }, "AuthenticateRequest": { "description": "Request parameters for the authenticate method.\n\nSpecifies which authentication method to use.", "properties": { @@ -568,10 +741,21 @@ "description": "The _meta property is reserved by ACP to allow clients and agents to attach 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"] }, + "auth": { + "allOf": [ + { + "$ref": "#/$defs/AuthCapabilities" + } + ], + "default": { + "terminal": false + }, + "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`." + }, "fs": { "allOf": [ { - "$ref": "#/$defs/FileSystemCapability" + "$ref": "#/$defs/FileSystemCapabilities" } ], "default": { @@ -703,6 +887,15 @@ "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResumes an existing session without returning previous messages.\n\nThis method is only available if the agent advertises the `session.resume` capability.\n\nThe agent should resume the session context, allowing the conversation to continue\nwithout replaying the message history (unlike `session/load`).", "title": "ResumeSessionRequest" }, + { + "allOf": [ + { + "$ref": "#/$defs/StopSessionRequest" + } + ], + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nStops an active session and frees up any resources associated with it.\n\nThis method is only available if the agent advertises the `session.stop` capability.\n\nThe agent must cancel any ongoing work (as if `session/cancel` was called)\nand then free up any resources associated with the session.", + "title": "StopSessionRequest" + }, { "allOf": [ { @@ -829,7 +1022,7 @@ { "allOf": [ { - "$ref": "#/$defs/KillTerminalCommandResponse" + "$ref": "#/$defs/KillTerminalResponse" } ], "title": "KillTerminalResponse" @@ -1008,6 +1201,10 @@ } ], "description": "A single item of content" + }, + "messageId": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA unique identifier for the message this chunk belongs to.\n\nAll chunks belonging to the same message share the same `messageId`.\nA change in `messageId` indicates a new message has started.\nBoth clients and agents MUST use UUID format for message IDs.", + "type": ["string", "null"] } }, "required": ["content"], @@ -1210,6 +1407,13 @@ "Error": { "description": "JSON-RPC error object.\n\nRepresents an error that occurred during method execution, following the\nJSON-RPC 2.0 error object specification with optional additional data.\n\nSee protocol docs: [JSON-RPC Error Object](https://www.jsonrpc.org/specification#error_object)", "properties": { + "authMethods": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nAuthentication methods relevant to this error.\nTypically included with `AUTH_REQUIRED` errors to narrow down which\nauthentication methods are applicable from those shared during initialization.", + "items": { + "$ref": "#/$defs/AuthMethod" + }, + "type": "array" + }, "code": { "allOf": [ { @@ -1305,8 +1509,8 @@ "ExtResponse": { "description": "Allows for sending an arbitrary response to an [`ExtRequest`] that is not part of the ACP spec.\nExtension methods provide a way to add custom functionality while maintaining\nprotocol compatibility.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)" }, - "FileSystemCapability": { - "description": "Filesystem capabilities supported by the client.\nFile system capabilities that a client may support.\n\nSee protocol docs: [FileSystem](https://agentclientprotocol.com/protocol/initialization#filesystem)", + "FileSystemCapabilities": { + "description": "File system capabilities that a client may support.\n\nSee protocol docs: [FileSystem](https://agentclientprotocol.com/protocol/initialization#filesystem)", "properties": { "_meta": { "additionalProperties": true, @@ -1500,6 +1704,9 @@ } ], "default": { + "auth": { + "terminal": false + }, "fs": { "readTextFile": false, "writeTextFile": false @@ -1595,8 +1802,8 @@ "x-method": "initialize", "x-side": "agent" }, - "KillTerminalCommandRequest": { - "description": "Request to kill a terminal command without releasing the terminal.", + "KillTerminalRequest": { + "description": "Request to kill a terminal without releasing it.", "properties": { "_meta": { "additionalProperties": true, @@ -1621,8 +1828,8 @@ "x-method": "terminal/kill", "x-side": "client" }, - "KillTerminalCommandResponse": { - "description": "Response to terminal/kill command method", + "KillTerminalResponse": { + "description": "Response to `terminal/kill` method", "properties": { "_meta": { "additionalProperties": true, @@ -2204,6 +2411,10 @@ "description": "The _meta property is reserved by ACP to allow clients and agents to attach 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"] }, + "messageId": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA client-generated unique identifier for this user message.\n\nIf provided, the Agent SHOULD echo this value as `userMessageId` in the\n[`PromptResponse`] to confirm it was recorded.\nBoth clients and agents MUST use UUID format for message IDs.", + "type": ["string", "null"] + }, "prompt": { "description": "The blocks of content that compose the user's message.\n\nAs a baseline, the Agent MUST support [`ContentBlock::Text`] and [`ContentBlock::ResourceLink`],\nwhile other variants are optionally enabled via [`PromptCapabilities`].\n\nThe Client MUST adapt its interface according to [`PromptCapabilities`].\n\nThe client MAY include referenced pieces of context as either\n[`ContentBlock::Resource`] or [`ContentBlock::ResourceLink`].\n\nWhen available, [`ContentBlock::Resource`] is preferred\nas it avoids extra round-trips and allows the message to include\npieces of context from sources the agent may not have access to.", "items": { @@ -2251,6 +2462,10 @@ } ], "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nToken usage for this turn (optional)." + }, + "userMessageId": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe acknowledged user message ID.\n\nIf the client provided a `messageId` in the [`PromptRequest`], the agent echoes it here\nto confirm it was recorded. If the client did not provide one, the agent MAY assign one\nand return it here. Absence of this field indicates the agent did not record a message ID.", + "type": ["string", "null"] } }, "required": ["stopReason"], @@ -2652,6 +2867,17 @@ } ], "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhether the agent supports `session/resume`." + }, + "stop": { + "anyOf": [ + { + "$ref": "#/$defs/SessionStopCapabilities" + }, + { + "type": "null" + } + ], + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhether the agent supports `session/stop`." } }, "type": "object" @@ -3053,6 +3279,17 @@ }, "type": "object" }, + "SessionStopCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapabilities for the `session/stop` method.\n\nBy supplying `{}` it means that the agent supports stopping of sessions.", + "properties": { + "_meta": { + "additionalProperties": true, + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "type": ["object", "null"] + } + }, + "type": "object" + }, "SessionUpdate": { "description": "Different types of updates that can be sent during session processing.\n\nThese updates provide real-time feedback about the agent's progress.\n\nSee protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output)", "discriminator": { @@ -3331,6 +3568,7 @@ "properties": { "_meta": { "additionalProperties": true, + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", "type": ["object", "null"] } }, @@ -3411,6 +3649,41 @@ } ] }, + "StopSessionRequest": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for stopping an active session.\n\nIf supported, the agent **must** cancel any ongoing work related to the session\n(treat it as if `session/cancel` was called) and then free up any resources\nassociated with the session.\n\nOnly available if the Agent supports the `session.stop` capability.", + "properties": { + "_meta": { + "additionalProperties": true, + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "type": ["object", "null"] + }, + "sessionId": { + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ], + "description": "The ID of the session to stop." + } + }, + "required": ["sessionId"], + "type": "object", + "x-method": "session/stop", + "x-side": "agent" + }, + "StopSessionResponse": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse from stopping a session.", + "properties": { + "_meta": { + "additionalProperties": true, + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)", + "type": ["object", "null"] + } + }, + "type": "object", + "x-method": "session/stop", + "x-side": "agent" + }, "Terminal": { "description": "Embed a terminal created with `terminal/create` by its id.\n\nThe terminal must be added before calling `terminal/release`.\n\nSee protocol docs: [Terminal](https://agentclientprotocol.com/protocol/terminals)", "properties": { @@ -4113,7 +4386,7 @@ "$ref": "#/$defs/CancelRequestNotification" } ], - "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or\nchanged at any point.\n\nCancels an ongoing request.\n\nThis is a notification sent by the the side that sent a request to cancel that request.\n\nUpon receiving this notification, the receiver:\n\n1. MUST cancel the corresponding request activity and all nested activities\n2. MAY send any pending notifications.\n3. MUST send one of these responses for the original request:\n - Valid response with appropriate data (partial results or cancellation marker)\n - Error response with code `-32800` (Cancelled)\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation)", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or\nchanged at any point.\n\nCancels an ongoing request.\n\nThis is a notification sent by the side that sent a request to cancel that request.\n\nUpon receiving this notification, the receiver:\n\n1. MUST cancel the corresponding request activity and all nested activities\n2. MAY send any pending notifications.\n3. MUST send one of these responses for the original request:\n - Valid response with appropriate data (partial results or cancellation marker)\n - Error response with code `-32800` (Cancelled)\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation)", "title": "CancelRequestNotification" } ], diff --git a/scripts/generate.js b/scripts/generate.js index efced26a..72073045 100644 --- a/scripts/generate.js +++ b/scripts/generate.js @@ -5,7 +5,7 @@ import * as fs from "fs/promises"; import { dirname } from "path"; import * as prettier from "prettier"; -const CURRENT_SCHEMA_RELEASE = "v0.10.8"; +const CURRENT_SCHEMA_RELEASE = "v0.11.0"; await main(); diff --git a/src/acp.ts b/src/acp.ts index 171ff527..b93cd7c3 100644 --- a/src/acp.ts +++ b/src/acp.ts @@ -399,7 +399,7 @@ export class TerminalHandle { * * Useful for implementing timeouts or cancellation. */ - async kill(): Promise { + async kill(): Promise { return ( (await this.#connection.sendRequest(schema.CLIENT_METHODS.terminal_kill, { sessionId: this.#sessionId, @@ -503,8 +503,7 @@ export class ClientSideConnection implements Agent { return client.waitForTerminalExit?.(validatedParams); } case schema.CLIENT_METHODS.terminal_kill: { - const validatedParams = - validate.zKillTerminalCommandRequest.parse(params); + const validatedParams = validate.zKillTerminalRequest.parse(params); const result = await client.killTerminal?.(validatedParams); return result ?? {}; } @@ -1384,8 +1383,8 @@ export interface Client { * @see {@link https://agentclientprotocol.com/protocol/terminals#killing-commands | Killing Commands} */ killTerminal?( - params: schema.KillTerminalCommandRequest, - ): Promise; + params: schema.KillTerminalRequest, + ): Promise; /** * Extension method diff --git a/src/schema/index.ts b/src/schema/index.ts index 958bc84d..4368ca02 100644 --- a/src/schema/index.ts +++ b/src/schema/index.ts @@ -7,9 +7,14 @@ export type { AgentResponse, Annotations, AudioContent, + AuthCapabilities, AuthenticateRequest, AuthenticateResponse, + AuthEnvVar, AuthMethod, + AuthMethodAgent, + AuthMethodEnvVar, + AuthMethodTerminal, AvailableCommand, AvailableCommandInput, AvailableCommandsUpdate, @@ -37,7 +42,7 @@ export type { ExtNotification, ExtRequest, ExtResponse, - FileSystemCapability, + FileSystemCapabilities, ForkSessionRequest, ForkSessionResponse, HttpHeader, @@ -45,8 +50,8 @@ export type { Implementation, InitializeRequest, InitializeResponse, - KillTerminalCommandRequest, - KillTerminalCommandResponse, + KillTerminalRequest, + KillTerminalResponse, ListSessionsRequest, ListSessionsResponse, LoadSessionRequest, @@ -105,6 +110,7 @@ export type { SessionModeState, SessionNotification, SessionResumeCapabilities, + SessionStopCapabilities, SessionUpdate, SetSessionConfigOptionRequest, SetSessionConfigOptionResponse, @@ -113,6 +119,8 @@ export type { SetSessionModeRequest, SetSessionModeResponse, StopReason, + StopSessionRequest, + StopSessionResponse, Terminal, TerminalExitStatus, TerminalOutputRequest, @@ -148,6 +156,7 @@ export const AGENT_METHODS = { session_set_config_option: "session/set_config_option", session_set_mode: "session/set_mode", session_set_model: "session/set_model", + session_stop: "session/stop", } as const; export const CLIENT_METHODS = { diff --git a/src/schema/types.gen.ts b/src/schema/types.gen.ts index b6104f40..30cc8719 100644 --- a/src/schema/types.gen.ts +++ b/src/schema/types.gen.ts @@ -55,7 +55,7 @@ export type AgentRequest = { | TerminalOutputRequest | ReleaseTerminalRequest | WaitForTerminalExitRequest - | KillTerminalCommandRequest + | KillTerminalRequest | ExtRequest | null; }; @@ -79,6 +79,7 @@ export type AgentResponse = | ListSessionsResponse | ForkSessionResponse | ResumeSessionResponse + | StopSessionResponse | SetSessionModeResponse | SetSessionConfigOptionResponse | PromptResponse @@ -128,10 +129,182 @@ export type AudioContent = { mimeType: string; }; +/** + * **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 = { + /** + * The _meta property is reserved by ACP to allow clients and agents to 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; + /** + * Whether the client supports `terminal` authentication methods. + * + * When `true`, the agent may include `terminal` entries in its authentication methods. + */ + terminal?: boolean; +}; + +/** + * **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 _meta property is reserved by ACP to allow clients and agents to 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; + /** + * Human-readable label for this variable, displayed in client UI. + */ + label?: string | null; + /** + * The environment variable name (e.g. `"OPENAI_API_KEY"`). + */ + name: string; + /** + * Whether this variable is optional. + * + * Defaults to `false`. + */ + optional?: boolean; + /** + * 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; +}; + /** * Describes an available authentication method. + * + * The `type` field acts as the discriminator in the serialized JSON form. + * When no `type` is present, the method is treated as `agent`. + */ +export type AuthMethod = + | (AuthMethodEnvVar & { + type: "env_var"; + }) + | (AuthMethodTerminal & { + type: "terminal"; + }) + | AuthMethodAgent; + +/** + * Agent handles authentication itself. + * + * This is the default authentication method type. + */ +export type AuthMethodAgent = { + /** + * The _meta property is reserved by ACP to allow clients and agents to 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; + /** + * Optional description providing more details about this authentication method. + */ + description?: string | null; + /** + * Unique identifier for this authentication method. + */ + id: string; + /** + * Human-readable name of the authentication method. + */ + name: string; +}; + +/** + * **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 = { + /** + * The _meta property is reserved by ACP to allow clients and agents to 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; + /** + * Optional description providing more details about this authentication method. + */ + description?: string | null; + /** + * Unique identifier for this authentication method. + */ + id: string; + /** + * Optional link to a page where the user can obtain their credentials. + */ + link?: string | null; + /** + * Human-readable name of the authentication method. + */ + name: string; + /** + * The environment variables the client should set. + */ + vars: Array; +}; + +/** + * **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 */ -export type AuthMethod = { +export type AuthMethodTerminal = { /** * The _meta property is reserved by ACP to allow clients and agents to attach additional * metadata to their interactions. Implementations MUST NOT make assumptions about values at @@ -142,10 +315,20 @@ export type AuthMethod = { _meta?: { [key: string]: unknown; } | null; + /** + * Additional arguments to pass when running the agent binary for terminal auth. + */ + args?: Array; /** * Optional description providing more details about this authentication method. */ description?: string | null; + /** + * Additional environment variables to set when running the agent binary for terminal auth. + */ + env?: { + [key: string]: string; + }; /** * Unique identifier for this authentication method. */ @@ -338,11 +521,23 @@ export type ClientCapabilities = { _meta?: { [key: string]: unknown; } | 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; /** * File system capabilities supported by the client. * Determines which file operations the agent can request. */ - fs?: FileSystemCapability; + fs?: FileSystemCapabilities; /** * Whether the Client support all `terminal*` methods. */ @@ -365,6 +560,7 @@ export type ClientRequest = { | ListSessionsRequest | ForkSessionRequest | ResumeSessionRequest + | StopSessionRequest | SetSessionModeRequest | SetSessionConfigOptionRequest | PromptRequest @@ -392,7 +588,7 @@ export type ClientResponse = | TerminalOutputResponse | ReleaseTerminalResponse | WaitForTerminalExitResponse - | KillTerminalCommandResponse + | KillTerminalResponse | ExtResponse; } | { @@ -491,6 +687,20 @@ export type ContentChunk = { * A single item of content */ content: ContentBlock; + /** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * A unique identifier for the message this chunk belongs to. + * + * All chunks belonging to the same message share the same `messageId`. + * A change in `messageId` indicates a new message has started. + * Both clients and agents MUST use UUID format for message IDs. + * + * @experimental + */ + messageId?: string | null; }; /** @@ -692,6 +902,18 @@ export type EnvVariable = { * See protocol docs: [JSON-RPC Error Object](https://www.jsonrpc.org/specification#error_object) */ export type Error = { + /** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Authentication methods relevant to this error. + * Typically included with `AUTH_REQUIRED` errors to narrow down which + * authentication methods are applicable from those shared during initialization. + * + * @experimental + */ + authMethods?: Array; /** * A number indicating the error type that occurred. * This must be an integer as defined in the JSON-RPC specification. @@ -754,12 +976,11 @@ export type ExtRequest = unknown; export type ExtResponse = unknown; /** - * Filesystem capabilities supported by the client. * File system capabilities that a client may support. * * See protocol docs: [FileSystem](https://agentclientprotocol.com/protocol/initialization#filesystem) */ -export type FileSystemCapability = { +export type FileSystemCapabilities = { /** * The _meta property is reserved by ACP to allow clients and agents to attach additional * metadata to their interactions. Implementations MUST NOT make assumptions about values at @@ -1020,9 +1241,9 @@ export type InitializeResponse = { }; /** - * Request to kill a terminal command without releasing the terminal. + * Request to kill a terminal without releasing it. */ -export type KillTerminalCommandRequest = { +export type KillTerminalRequest = { /** * The _meta property is reserved by ACP to allow clients and agents to attach additional * metadata to their interactions. Implementations MUST NOT make assumptions about values at @@ -1044,9 +1265,9 @@ export type KillTerminalCommandRequest = { }; /** - * Response to terminal/kill command method + * Response to `terminal/kill` method */ -export type KillTerminalCommandResponse = { +export type KillTerminalResponse = { /** * The _meta property is reserved by ACP to allow clients and agents to attach additional * metadata to their interactions. Implementations MUST NOT make assumptions about values at @@ -1617,6 +1838,20 @@ export type PromptRequest = { _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 client-generated unique identifier for this user message. + * + * If provided, the Agent SHOULD echo this value as `userMessageId` in the + * [`PromptResponse`] to confirm it was recorded. + * Both clients and agents MUST use UUID format for message IDs. + * + * @experimental + */ + messageId?: string | null; /** * The blocks of content that compose the user's message. * @@ -1669,6 +1904,20 @@ export type PromptResponse = { * @experimental */ usage?: Usage | null; + /** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * The acknowledged user message ID. + * + * If the client provided a `messageId` in the [`PromptRequest`], the agent echoes it here + * to confirm it was recorded. If the client did not provide one, the agent MAY assign one + * and return it here. Absence of this field indicates the agent did not record a message ID. + * + * @experimental + */ + userMessageId?: string | null; }; /** @@ -2027,6 +2276,16 @@ export type SessionCapabilities = { * @experimental */ resume?: SessionResumeCapabilities | null; + /** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Whether the agent supports `session/stop`. + * + * @experimental + */ + stop?: SessionStopCapabilities | null; }; /** @@ -2420,6 +2679,30 @@ export type SessionResumeCapabilities = { } | null; }; +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Capabilities for the `session/stop` method. + * + * By supplying `{}` it means that the agent supports stopping of sessions. + * + * @experimental + */ +export type SessionStopCapabilities = { + /** + * The _meta property is reserved by ACP to allow clients and agents to 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; +}; + /** * Different types of updates that can be sent during session processing. * @@ -2538,6 +2821,13 @@ export type SetSessionModeRequest = { * Response to `session/set_mode` method. */ export type SetSessionModeResponse = { + /** + * The _meta property is reserved by ACP to allow clients and agents to 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; @@ -2607,6 +2897,60 @@ export type StopReason = | "refusal" | "cancelled"; +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Request parameters for stopping an active session. + * + * If supported, the agent **must** cancel any ongoing work related to the session + * (treat it as if `session/cancel` was called) and then free up any resources + * associated with the session. + * + * Only available if the Agent supports the `session.stop` capability. + * + * @experimental + */ +export type StopSessionRequest = { + /** + * The _meta property is reserved by ACP to allow clients and agents to 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; + /** + * The ID of the session to stop. + */ + sessionId: SessionId; +}; + +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Response from stopping a session. + * + * @experimental + */ +export type StopSessionResponse = { + /** + * The _meta property is reserved by ACP to allow clients and agents to 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; +}; + /** * Embed a terminal created with `terminal/create` by its id. * diff --git a/src/schema/zod.gen.ts b/src/schema/zod.gen.ts index d40bf207..0d853f77 100644 --- a/src/schema/zod.gen.ts +++ b/src/schema/zod.gen.ts @@ -3,15 +3,112 @@ import { z } from "zod/v4"; /** - * Describes an available authentication method. + * **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({ + _meta: z.record(z.string(), z.unknown()).nullish(), + terminal: z.boolean().optional().default(false), +}); + +/** + * **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({ + _meta: z.record(z.string(), z.unknown()).nullish(), + label: z.string().nullish(), + name: z.string(), + optional: z.boolean().optional().default(false), + secret: z.boolean().optional().default(true), +}); + +/** + * Agent handles authentication itself. + * + * This is the default authentication method type. + */ +export const zAuthMethodAgent = z.object({ + _meta: z.record(z.string(), z.unknown()).nullish(), + description: z.string().nullish(), + id: z.string(), + name: z.string(), +}); + +/** + * **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({ + _meta: z.record(z.string(), z.unknown()).nullish(), + description: z.string().nullish(), + id: z.string(), + link: z.string().nullish(), + name: z.string(), + vars: z.array(zAuthEnvVar), +}); + +/** + * **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 */ -export const zAuthMethod = z.object({ +export const zAuthMethodTerminal = z.object({ _meta: z.record(z.string(), z.unknown()).nullish(), + args: z.array(z.string()).optional(), description: z.string().nullish(), + env: z.record(z.string(), z.string()).optional(), id: z.string(), name: z.string(), }); +/** + * Describes an available authentication method. + * + * The `type` field acts as the discriminator in the serialized JSON form. + * When no `type` is present, the method is treated as `agent`. + */ +export const zAuthMethod = z.union([ + zAuthMethodEnvVar.and( + z.object({ + type: z.literal("env_var"), + }), + ), + zAuthMethodTerminal.and( + z.object({ + type: z.literal("terminal"), + }), + ), + zAuthMethodAgent, +]); + /** * Request parameters for the authenticate method. * @@ -152,12 +249,11 @@ export const zExtRequest = z.unknown(); export const zExtResponse = z.unknown(); /** - * Filesystem capabilities supported by the client. * File system capabilities that a client may support. * * See protocol docs: [FileSystem](https://agentclientprotocol.com/protocol/initialization#filesystem) */ -export const zFileSystemCapability = z.object({ +export const zFileSystemCapabilities = z.object({ _meta: z.record(z.string(), z.unknown()).nullish(), readTextFile: z.boolean().optional().default(false), writeTextFile: z.boolean().optional().default(false), @@ -173,7 +269,8 @@ export const zFileSystemCapability = z.object({ */ export const zClientCapabilities = z.object({ _meta: z.record(z.string(), z.unknown()).nullish(), - fs: zFileSystemCapability + auth: zAuthCapabilities.optional().default({ terminal: false }), + fs: zFileSystemCapabilities .optional() .default({ readTextFile: false, writeTextFile: false }), terminal: z.boolean().optional().default(false), @@ -201,9 +298,9 @@ export const zImplementation = z.object({ }); /** - * Response to terminal/kill command method + * Response to `terminal/kill` method */ -export const zKillTerminalCommandResponse = z.object({ +export const zKillTerminalResponse = z.object({ _meta: z.record(z.string(), z.unknown()).nullish(), }); @@ -443,6 +540,7 @@ export const zProtocolVersion = z.number().int().gte(0).lte(65535); export const zInitializeRequest = z.object({ _meta: z.record(z.string(), z.unknown()).nullish(), clientCapabilities: zClientCapabilities.optional().default({ + auth: { terminal: false }, fs: { readTextFile: false, writeTextFile: false }, terminal: false, }), @@ -742,9 +840,9 @@ export const zForkSessionRequest = z.object({ }); /** - * Request to kill a terminal command without releasing the terminal. + * Request to kill a terminal without releasing it. */ -export const zKillTerminalCommandRequest = z.object({ +export const zKillTerminalRequest = z.object({ _meta: z.record(z.string(), z.unknown()).nullish(), sessionId: zSessionId, terminalId: z.string(), @@ -998,6 +1096,21 @@ export const zSessionResumeCapabilities = z.object({ _meta: z.record(z.string(), z.unknown()).nullish(), }); +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Capabilities for the `session/stop` method. + * + * By supplying `{}` it means that the agent supports stopping of sessions. + * + * @experimental + */ +export const zSessionStopCapabilities = z.object({ + _meta: z.record(z.string(), z.unknown()).nullish(), +}); + /** * Session capabilities supported by the agent. * @@ -1014,6 +1127,7 @@ export const zSessionCapabilities = z.object({ fork: zSessionForkCapabilities.nullish(), list: zSessionListCapabilities.nullish(), resume: zSessionResumeCapabilities.nullish(), + stop: zSessionStopCapabilities.nullish(), }); /** @@ -1137,6 +1251,39 @@ export const zStopReason = z.union([ z.literal("cancelled"), ]); +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Request parameters for stopping an active session. + * + * If supported, the agent **must** cancel any ongoing work related to the session + * (treat it as if `session/cancel` was called) and then free up any resources + * associated with the session. + * + * Only available if the Agent supports the `session.stop` capability. + * + * @experimental + */ +export const zStopSessionRequest = z.object({ + _meta: z.record(z.string(), z.unknown()).nullish(), + sessionId: zSessionId, +}); + +/** + * **UNSTABLE** + * + * This capability is not part of the spec yet, and may be removed or changed at any point. + * + * Response from stopping a session. + * + * @experimental + */ +export const zStopSessionResponse = z.object({ + _meta: z.record(z.string(), z.unknown()).nullish(), +}); + /** * Embed a terminal created with `terminal/create` by its id. * @@ -1278,6 +1425,7 @@ export const zContent = z.object({ export const zContentChunk = z.object({ _meta: z.record(z.string(), z.unknown()).nullish(), content: zContentBlock, + messageId: z.string().nullish(), }); /** @@ -1289,6 +1437,7 @@ export const zContentChunk = z.object({ */ export const zPromptRequest = z.object({ _meta: z.record(z.string(), z.unknown()).nullish(), + messageId: z.string().nullish(), prompt: z.array(zContentBlock), sessionId: zSessionId, }); @@ -1305,6 +1454,7 @@ export const zClientRequest = z.object({ zListSessionsRequest, zForkSessionRequest, zResumeSessionRequest, + zStopSessionRequest, zSetSessionModeRequest, zSetSessionConfigOptionRequest, zPromptRequest, @@ -1515,6 +1665,7 @@ export const zPromptResponse = z.object({ _meta: z.record(z.string(), z.unknown()).nullish(), stopReason: zStopReason, usage: zUsage.nullish(), + userMessageId: z.string().nullish(), }); export const zAgentResponse = z.union([ @@ -1528,6 +1679,7 @@ export const zAgentResponse = z.union([ zListSessionsResponse, zForkSessionResponse, zResumeSessionResponse, + zStopSessionResponse, zSetSessionModeResponse, zSetSessionConfigOptionResponse, zPromptResponse, @@ -1689,7 +1841,7 @@ export const zAgentRequest = z.object({ zTerminalOutputRequest, zReleaseTerminalRequest, zWaitForTerminalExitRequest, - zKillTerminalCommandRequest, + zKillTerminalRequest, zExtRequest, ]) .nullish(), @@ -1713,7 +1865,7 @@ export const zClientResponse = z.union([ zTerminalOutputResponse, zReleaseTerminalResponse, zWaitForTerminalExitResponse, - zKillTerminalCommandResponse, + zKillTerminalResponse, zExtResponse, ]), }),