Send available commands over notifications (agentclientprotocol#62)

Co-authored-by: Cole Miller <cole@zed.dev>

Author: 2 people

docs/protocol/schema.mdx

@@ -250,12 +250,6 @@ See protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol
 
 **Properties:**
 
-<ResponseField name="availableCommands" type={<><span><a href="#availablecommand">AvailableCommand</a></span><span>[]</span></>} >
-  **UNSTABLE**
-
-Commands that may be executed via `session/prompt` requests
-
-</ResponseField>
 <ResponseField name="sessionId" type={<a href="#sessionid">SessionId</a>} required>
   Unique identifier for the created session.
 
@@ -1518,6 +1512,28 @@ with their current status. The client replaces the entire plan with each update.
 </Expandable>
 </ResponseField>
 
+<ResponseField name="available_commands_update">
+Available commands are ready or have changed
+
+<Expandable title="Properties">
+
+<ResponseField
+  name="availableCommands"
+  type={
+    <>
+      <span>
+        <a href="#availablecommand">AvailableCommand</a>
+      </span>
+      <span>[]</span>
+    </>
+  }
+  required
+></ResponseField>
+<ResponseField name="sessionUpdate" type={"string"} required></ResponseField>
+
+</Expandable>
+</ResponseField>
+
 ## <span class="font-mono">StopReason</span>
 
 Reasons why an agent stops processing a prompt turn.

rust/agent.rs

@@ -204,37 +204,6 @@ pub struct NewSessionResponse {
     ///
     /// Used in all subsequent requests for this conversation.
     pub session_id: SessionId,
-    /// **UNSTABLE**
-    ///
-    /// Commands that may be executed via `session/prompt` requests
-    #[cfg(feature = "unstable")]
-    #[serde(default, skip_serializing_if = "Vec::is_empty")]
-    pub available_commands: Vec<AvailableCommand>,
-}
-
-/// 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,
-    /// Human-readable description of what the command does.
-    pub description: String,
-    /// Input for the command if required
-    pub input: Option<AvailableCommandInput>,
-}
-
-#[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
-        hint: String,
-    },
 }
 
 // Load session

rust/client.rs

@@ -158,6 +158,38 @@ pub enum SessionUpdate {
     /// The agent's execution plan for complex tasks.
     /// 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>,
+    },
+}
+
+/// 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,
+    /// Human-readable description of what the command does.
+    pub description: String,
+    /// Input for the command if required
+    pub input: Option<AvailableCommandInput>,
+}
+
+#[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
+        hint: String,
+    },
 }
 
 // Permission

schema/schema.json

@@ -765,13 +765,6 @@
     "NewSessionResponse": {
       "description": "Response from creating a new session.\n\nSee protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/session-setup#creating-a-session)",
       "properties": {
-        "availableCommands": {
-          "description": "**UNSTABLE**\n\nCommands that may be executed via `session/prompt` requests",
-          "items": {
-            "$ref": "#/$defs/AvailableCommand"
-          },
-          "type": "array"
-        },
         "sessionId": {
           "$ref": "#/$defs/SessionId",
           "description": "Unique identifier for the created session.\n\nUsed in all subsequent requests for this conversation."
@@ -1316,6 +1309,24 @@
           },
           "required": ["sessionUpdate", "entries"],
           "type": "object"
+        },
+        {
+          "description": "Available commands are ready or have changed",
+          "properties": {
+            "availableCommands": {
+              "items": {
+                "$ref": "#/$defs/AvailableCommand"
+              },
+              "type": "array"
+            },
+            "sessionUpdate": {
+              "const": "available_commands_update",
+              "type": "string"
+            }
+          },
+          "required": ["sessionUpdate", "availableCommands"],
+          "type": "object",
+          "x-docs-ignore": true
         }
       ]
     },