diff --git a/docs/docs.json b/docs/docs.json index 9f253586..a2013f6a 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -59,6 +59,7 @@ "protocol/terminals", "protocol/agent-plan", "protocol/session-modes", + "protocol/slash-commands", "protocol/extensibility", "protocol/schema" ] diff --git a/docs/protocol/overview.mdx b/docs/protocol/overview.mdx index 0b3174cd..a8dbf1dd 100644 --- a/docs/protocol/overview.mdx +++ b/docs/protocol/overview.mdx @@ -84,6 +84,14 @@ Agents are programs that use generative AI to autonomously modify code. They typ `loadSession` capability). +Schema]} +> + [Switch between agent operating + modes](./session-modes#setting-the-current-mode). + + ### Notifications Schema]} > - [Send progress updates](./prompt-turn#3-agent-reports-output) during prompt - processing (no response expected). + [Send session updates](./prompt-turn#3-agent-reports-output) to inform the + Client of changes (no response expected). This includes: - [Message + chunks](./content) (agent, user, thought) - [Tool calls and + updates](./tool-calls) - [Plans](./agent-plan) - [Available commands + updates](./slash-commands#advertising-commands) - [Mode + changes](./session-modes#from-the-agent) ## Argument requirements diff --git a/docs/protocol/schema.mdx b/docs/protocol/schema.mdx index d6751bfe..3adde8c7 100644 --- a/docs/protocol/schema.mdx +++ b/docs/protocol/schema.mdx @@ -1098,6 +1098,8 @@ Information about a command. ## AvailableCommandInput +The input specification for a command. + **Type:** Union @@ -1106,7 +1108,7 @@ All text that was typed after the command name is provided as input. - A brief description of the expected input + A hint to display when the input hasn't been provided yet @@ -2225,6 +2227,8 @@ Available commands are ready or have changed The current mode of the session has changed +See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes) + + The list of commands available in this session + + +### AvailableCommand + + + The command name (e.g., "web", "test", "plan") + + + + Human-readable description of what the command does + + + + Optional input specification for the command + + +### AvailableCommandInput + +Currently supports unstructured text input: + + + A hint to display when the input hasn't been provided yet + + +## Dynamic updates + +The Agent can update the list of available commands at any time during a session by sending another `available_commands_update` notification. This allows commands to be added based on context, removed when no longer relevant, or modified with updated descriptions. + +## Running commands + +Commands are included as regular user messages in prompt requests: + +```json +{ + "jsonrpc": "2.0", + "id": 3, + "method": "session/prompt", + "params": { + "sessionId": "sess_abc123def456", + "prompt": [ + { + "type": "text", + "text": "/web agent client protocol" + } + ] + } +} +``` + +The Agent recognizes the command prefix and processes it accordingly. Commands may be accompanied by any other user message content types (images, audio, etc.) in the same prompt array. diff --git a/rust/client.rs b/rust/client.rs index b66eb817..eb87b1f8 100644 --- a/rust/client.rs +++ b/rust/client.rs @@ -214,22 +214,20 @@ pub enum SessionUpdate { /// See protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/agent-plan) Plan(Plan), /// Available commands are ready or have changed - #[cfg(feature = "unstable")] #[serde(rename_all = "camelCase")] - #[schemars(extend("x-docs-ignore" = true))] AvailableCommandsUpdate { available_commands: Vec, }, /// The current mode of the session has changed + /// + /// See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes) #[serde(rename_all = "camelCase")] - // todo! CurrentModeUpdate { current_mode_id: SessionModeId }, } /// Information about a command. #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)] #[serde(rename_all = "camelCase")] -#[cfg(feature = "unstable")] pub struct AvailableCommand { /// Command name (e.g., "create_plan", "research_codebase"). pub name: String, @@ -242,14 +240,14 @@ pub struct AvailableCommand { pub meta: Option, } +/// The input specification for a command. #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)] #[serde(untagged, rename_all = "camelCase")] -#[cfg(feature = "unstable")] pub enum AvailableCommandInput { /// All text that was typed after the command name is provided as input. #[schemars(rename = "UnstructuredCommandInput")] Unstructured { - /// A brief description of the expected input + /// A hint to display when the input hasn't been provided yet hint: String, }, } diff --git a/rust/example_client.rs b/rust/example_client.rs index 24688c4c..04f1c4c8 100644 --- a/rust/example_client.rs +++ b/rust/example_client.rs @@ -98,7 +98,8 @@ impl acp::Client for ExampleClient { | acp::SessionUpdate::ToolCall(_) | acp::SessionUpdate::ToolCallUpdate(_) | acp::SessionUpdate::Plan(_) - | acp::SessionUpdate::CurrentModeUpdate { .. } => {} + | acp::SessionUpdate::CurrentModeUpdate { .. } + | acp::SessionUpdate::AvailableCommandsUpdate { .. } => {} } Ok(()) } diff --git a/rust/rpc_tests.rs b/rust/rpc_tests.rs index bd3f6217..b42070fc 100644 --- a/rust/rpc_tests.rs +++ b/rust/rpc_tests.rs @@ -727,6 +727,7 @@ async fn test_full_conversation_flow() { found_tool_update = true; } } + SessionUpdate::AvailableCommandsUpdate { .. } => {} _ => {} } } diff --git a/schema/schema.json b/schema/schema.json index 02a8d318..83d5355b 100644 --- a/schema/schema.json +++ b/schema/schema.json @@ -254,7 +254,7 @@ "description": "All text that was typed after the command name is provided as input.", "properties": { "hint": { - "description": "A brief description of the expected input", + "description": "A hint to display when the input hasn't been provided yet", "type": "string" } }, @@ -262,7 +262,8 @@ "title": "UnstructuredCommandInput", "type": "object" } - ] + ], + "description": "The input specification for a command." }, "BlobResourceContents": { "description": "Binary resource contents.", @@ -1715,11 +1716,10 @@ } }, "required": ["sessionUpdate", "availableCommands"], - "type": "object", - "x-docs-ignore": true + "type": "object" }, { - "description": "The current mode of the session has changed", + "description": "The current mode of the session has changed\n\nSee protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)", "properties": { "currentModeId": { "$ref": "#/$defs/SessionModeId" diff --git a/typescript/schema.ts b/typescript/schema.ts index a58112cf..f3227bf7 100644 --- a/typescript/schema.ts +++ b/typescript/schema.ts @@ -401,6 +401,9 @@ export type SessionModeId = string; */ /** @internal */ export type AgentNotification = SessionNotification | ExtNotification1; +/** + * The input specification for a command. + */ export type AvailableCommandInput = UnstructuredCommandInput; /** @@ -1595,7 +1598,7 @@ export interface AvailableCommand { */ export interface UnstructuredCommandInput { /** - * A brief description of the expected input + * A hint to display when the input hasn't been provided yet */ hint: string; }