Stabilize Slash Commands API (#88)

* Checkpoint: Stabilizing commands

* Improve docs

Author: agu-z

docs/docs.json

@@ -59,6 +59,7 @@
           "protocol/terminals",
           "protocol/agent-plan",
           "protocol/session-modes",
+          "protocol/slash-commands",
           "protocol/extensibility",
           "protocol/schema"
         ]

docs/protocol/overview.mdx

@@ -84,6 +84,14 @@ Agents are programs that use generative AI to autonomously modify code. They typ
   `loadSession` capability).
 </ResponseField>
 
+<ResponseField
+  name="session/set_mode"
+  post={[<a href="./schema#session%2Fset-mode">Schema</a>]}
+>
+  [Switch between agent operating
+  modes](./session-modes#setting-the-current-mode).
+</ResponseField>
+
 ### Notifications
 
 <ResponseField
@@ -167,8 +175,12 @@ Clients provide the interface between users and agents. They are typically code
   name="session/update"
   post={[<a href="./schema#session%2Fupdate">Schema</a>]}
 >
-  [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)
 </ResponseField>
 
 ## Argument requirements

docs/protocol/schema.mdx

@@ -1098,6 +1098,8 @@ Information about a command.
 
 ## <span class="font-mono">AvailableCommandInput</span>
 
+The input specification for a command.
+
 **Type:** Union
 
 <ResponseField name="Object">
@@ -1106,7 +1108,7 @@ All text that was typed after the command name is provided as input.
 <Expandable title="Properties">
 
 <ResponseField name="hint" type={"string"} required>
-  A brief description of the expected input
+  A hint to display when the input hasn't been provided yet
 </ResponseField>
 
 </Expandable>
@@ -2225,6 +2227,8 @@ Available commands are ready or have changed
 <ResponseField name="current_mode_update">
 The current mode of the session has changed
 
+See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)
+
 <Expandable title="Properties">
 
 <ResponseField

docs/protocol/slash-commands.mdx

@@ -0,0 +1,96 @@
+---
+title: "Slash Commands"
+description: "Advertise available slash commands to clients"
+---
+
+Agents can advertise a set of slash commands that users can invoke. These commands provide quick access to specific agent capabilities and workflows. Commands are run as part of regular [prompt](./prompt-turn) requests where the Client includes the command text in the prompt.
+
+## Advertising commands
+
+After creating a session, the Agent **MAY** send a list of available commands via the `available_commands_update` session notification:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "session/update",
+  "params": {
+    "sessionId": "sess_abc123def456",
+    "update": {
+      "sessionUpdate": "available_commands_update",
+      "availableCommands": [
+        {
+          "name": "web",
+          "description": "Search the web for information",
+          "input": {
+            "hint": "query to search for"
+          }
+        },
+        {
+          "name": "test",
+          "description": "Run tests for the current project"
+        },
+        {
+          "name": "plan",
+          "description": "Create a detailed implementation plan",
+          "input": {
+            "hint": "description of what to plan"
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+<ResponseField name="availableCommands" type="AvailableCommand[]">
+  The list of commands available in this session
+</ResponseField>
+
+### AvailableCommand
+
+<ResponseField name="name" type="string" required>
+  The command name (e.g., "web", "test", "plan")
+</ResponseField>
+
+<ResponseField name="description" type="string" required>
+  Human-readable description of what the command does
+</ResponseField>
+
+<ResponseField name="input" type="AvailableCommandInput">
+  Optional input specification for the command
+</ResponseField>
+
+### AvailableCommandInput
+
+Currently supports unstructured text input:
+
+<ResponseField name="hint" type="string" required>
+  A hint to display when the input hasn't been provided yet
+</ResponseField>
+
+## 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.

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<AvailableCommand>,
     },
     /// 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<serde_json::Value>,
 }
 
+/// 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,
     },
 }

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(())
     }

rust/rpc_tests.rs

@@ -727,6 +727,7 @@ async fn test_full_conversation_flow() {
                             found_tool_update = true;
                         }
                     }
+                    SessionUpdate::AvailableCommandsUpdate { .. } => {}
                     _ => {}
                 }
             }

schema/schema.json

@@ -254,15 +254,16 @@
           "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"
             }
           },
           "required": ["hint"],
           "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"

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;
 }