feat: Stabilize session/list and session_info_update

Author: benbrandt

Cargo.toml

@@ -18,8 +18,6 @@ unstable = [
     "unstable_auth_methods",
     "unstable_cancel_request",
     "unstable_session_fork",
-    "unstable_session_info_update",
-    "unstable_session_list",
     "unstable_session_model",
     "unstable_session_resume",
     "unstable_session_close",
@@ -30,8 +28,6 @@ unstable = [
 unstable_auth_methods = []
 unstable_cancel_request = []
 unstable_session_fork = []
-unstable_session_info_update = []
-unstable_session_list = []
 unstable_session_model = []
 unstable_session_resume = []
 unstable_session_close = []

docs/docs.json

@@ -65,6 +65,7 @@
               "protocol/overview",
               "protocol/initialization",
               "protocol/session-setup",
+              "protocol/session-list",
               "protocol/prompt-turn",
               "protocol/content",
               "protocol/tool-calls",
@@ -82,7 +83,6 @@
                 "hidden": true,
                 "pages": [
                   "protocol/draft/cancellation",
-                  "protocol/draft/session-list",
                   "protocol/draft/schema"
                 ]
               }
@@ -128,17 +128,15 @@
           },
           {
             "group": "Preview",
-            "pages": [
-              "rfds/acp-agent-registry",
-              "rfds/session-list",
-              "rfds/session-info-update"
-            ]
+            "pages": ["rfds/acp-agent-registry"]
           },
           {
             "group": "Completed",
             "pages": [
               "rfds/introduce-rfd-process",
-              "rfds/session-config-options"
+              "rfds/session-config-options",
+              "rfds/session-list",
+              "rfds/session-info-update"
             ]
           }
         ]

docs/protocol/draft/schema.mdx

@@ -355,25 +355,17 @@ See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/sess
 <a id="session-list"></a>
 ### <span class="font-mono">session/list</span>
 
-**UNSTABLE**
-
-This capability is not part of the spec yet, and may be removed or changed at any point.
-
 Lists existing sessions known to the agent.
 
-This method is only available if the agent advertises the `listSessions` capability.
+This method is only available if the agent advertises the `sessionCapabilities.list` capability.
 
 The agent should return metadata about sessions with optional filtering and pagination support.
 
 #### <span class="font-mono">ListSessionsRequest</span>
 
-**UNSTABLE**
-
-This capability is not part of the spec yet, and may be removed or changed at any point.
-
 Request parameters for listing existing sessions.
 
-Only available if the Agent supports the `listSessions` capability.
+Only available if the Agent supports the `sessionCapabilities.list` capability.
 
 **Type:** Object
 
@@ -396,10 +388,6 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte
 
 #### <span class="font-mono">ListSessionsResponse</span>
 
-**UNSTABLE**
-
-This capability is not part of the spec yet, and may be removed or changed at any point.
-
 Response from listing sessions.
 
 **Type:** Object
@@ -3372,12 +3360,7 @@ Whether the agent supports `session/fork`.
 
 </ResponseField>
 <ResponseField name="list" type={<><span><a href="#sessionlistcapabilities">SessionListCapabilities</a></span><span> | null</span></>} >
-  **UNSTABLE**
-
-This capability is not part of the spec yet, and may be removed or changed at any point.
-
-Whether the agent supports `session/list`.
-
+  Whether the agent supports `session/list`.
 </ResponseField>
 <ResponseField name="resume" type={<><span><a href="#sessionresumecapabilities">SessionResumeCapabilities</a></span><span> | null</span></>} >
   **UNSTABLE**
@@ -3659,10 +3642,6 @@ See protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session
 
 ## <span class="font-mono">SessionInfo</span>
 
-**UNSTABLE**
-
-This capability is not part of the spec yet, and may be removed or changed at any point.
-
 Information about a session returned by session/list
 
 **Type:** Object
@@ -3722,8 +3701,6 @@ Capabilities for the `session/list` method.
 
 By supplying `\{\}` it means that the agent supports listing of sessions.
 
-Further capabilities can be added in the future for other means of filtering or searching the list.
-
 **Type:** Object
 
 **Properties:**

docs/protocol/schema.mdx

@@ -196,6 +196,64 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte
   The ID of the session to cancel operations for.
 </ResponseField>
 
+<a id="session-list"></a>
+### <span class="font-mono">session/list</span>
+
+Lists existing sessions known to the agent.
+
+This method is only available if the agent advertises the `sessionCapabilities.list` capability.
+
+The agent should return metadata about sessions with optional filtering and pagination support.
+
+#### <span class="font-mono">ListSessionsRequest</span>
+
+Request parameters for listing existing sessions.
+
+Only available if the Agent supports the `sessionCapabilities.list` capability.
+
+**Type:** Object
+
+**Properties:**
+
+<ResponseField name="_meta" type={"object | 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)
+
+</ResponseField>
+<ResponseField name="cursor" type={"string | null"} >
+  Opaque cursor token from a previous response's nextCursor field for cursor-based pagination
+</ResponseField>
+<ResponseField name="cwd" type={"string | null"} >
+  Filter sessions by working directory. Must be an absolute path.
+</ResponseField>
+
+#### <span class="font-mono">ListSessionsResponse</span>
+
+Response from listing sessions.
+
+**Type:** Object
+
+**Properties:**
+
+<ResponseField name="_meta" type={"object | 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)
+
+</ResponseField>
+<ResponseField name="nextCursor" type={"string | null"} >
+  Opaque cursor token. If present, pass this in the next request's cursor parameter
+to fetch the next page. If absent, there are no more results.
+</ResponseField>
+<ResponseField name="sessions" type={<a href="#sessioninfo">SessionInfo[]</a>} required>
+  Array of session information objects
+</ResponseField>
+
 <a id="session-load"></a>
 ### <span class="font-mono">session/load</span>
 
@@ -2533,6 +2591,9 @@ these keys.
 See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)
 
 </ResponseField>
+<ResponseField name="list" type={<><span><a href="#sessionlistcapabilities">SessionListCapabilities</a></span><span> | null</span></>} >
+  Whether the agent supports `session/list`.
+</ResponseField>
 
 ## <span class="font-mono">SessionConfigGroupId</span>
 
@@ -2707,6 +2768,80 @@ See protocol docs: [Session ID](https://agentclientprotocol.com/protocol/session
 
 **Type:** `string`
 
+## <span class="font-mono">SessionInfo</span>
+
+Information about a session returned by session/list
+
+**Type:** Object
+
+**Properties:**
+
+<ResponseField name="_meta" type={"object | 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)
+
+</ResponseField>
+<ResponseField name="cwd" type={"string"} required>
+  The working directory for this session. Must be an absolute path.
+</ResponseField>
+<ResponseField name="sessionId" type={<a href="#sessionid">SessionId</a>} required>
+  Unique identifier for the session
+</ResponseField>
+<ResponseField name="title" type={"string | null"} >
+  Human-readable title for the session
+</ResponseField>
+<ResponseField name="updatedAt" type={"string | null"} >
+  ISO 8601 timestamp of last activity
+</ResponseField>
+
+## <span class="font-mono">SessionInfoUpdate</span>
+
+Update to session metadata. All fields are optional to support partial updates.
+
+Agents send this notification to update session information like title or custom metadata.
+This allows clients to display dynamic session names and track session state changes.
+
+**Type:** Object
+
+**Properties:**
+
+<ResponseField name="_meta" type={"object | 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)
+
+</ResponseField>
+<ResponseField name="title" type={"string | null"} >
+  Human-readable title for the session. Set to null to clear.
+</ResponseField>
+<ResponseField name="updatedAt" type={"string | null"} >
+  ISO 8601 timestamp of last activity. Set to null to clear.
+</ResponseField>
+
+## <span class="font-mono">SessionListCapabilities</span>
+
+Capabilities for the `session/list` method.
+
+By supplying `\{\}` it means that the agent supports listing of sessions.
+
+**Type:** Object
+
+**Properties:**
+
+<ResponseField name="_meta" type={"object | 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)
+
+</ResponseField>
+
 ## <span class="font-mono">SessionMode</span>
 
 A mode the agent can operate in.
@@ -3029,6 +3164,32 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte
 </Expandable>
 </ResponseField>
 
+<ResponseField name="session_info_update" type="object">
+Session metadata has been updated (title, timestamps, custom metadata)
+
+<Expandable title="Properties">
+
+<ResponseField name="_meta" type={"object | 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)
+
+</ResponseField>
+<ResponseField name="sessionUpdate" type={"string"} required>
+  The discriminator value. Must be `"session_info_update"`.
+</ResponseField>
+<ResponseField name="title" type={"string | null"} >
+  Human-readable title for the session. Set to null to clear.
+</ResponseField>
+<ResponseField name="updatedAt" type={"string | null"} >
+  ISO 8601 timestamp of last activity. Set to null to clear.
+</ResponseField>
+
+</Expandable>
+</ResponseField>
+
 ## <span class="font-mono">StopReason</span>
 
 Reasons why an agent stops processing a prompt turn.

docs/protocol/draft/session-list.mdx docs/protocol/session-list.mdxdocs/protocol/draft/session-list.mdx renamed to docs/protocol/session-list.mdx

@@ -1,13 +1,13 @@
 ---
 title: "Session List"
-description: "Discovering and enumerating existing sessions"
+description: "Discovering existing sessions"
 ---
 
-The `session/list` method allows Clients to discover and enumerate sessions known to an Agent. Clients can use this to display session history and switch between sessions.
+The `session/list` method allows Clients to discover sessions known to an Agent. Clients can use this to display session history and switch between sessions.
 
 Agents can also push session metadata updates to Clients in real-time via the `session_info_update` notification, keeping session titles and metadata in sync without polling.
 
-Before listing sessions, Clients **MUST** first complete the [initialization](../initialization) phase to verify the Agent supports this capability.
+Before listing sessions, Clients **MUST** first complete the [initialization](./initialization) phase to verify the Agent supports this capability.
 
 <br />
 
@@ -133,7 +133,7 @@ The Agent **MUST** respond with a list of sessions and optional pagination metad
       ISO 8601 timestamp of the last activity in the session.
     </ResponseField>
     <ResponseField name="_meta" type="object">
-      Agent-specific metadata. See [Extensibility](../extensibility).
+      Agent-specific metadata. See [Extensibility](./extensibility).
     </ResponseField>
   </Expandable>
 </ResponseField>
@@ -156,7 +156,7 @@ When no sessions match the criteria, the Agent **MUST** return an empty `session
 
 ## Updating Session Metadata
 
-Agents can update session metadata in real-time by sending a `session_info_update` notification via `session/update`. This follows the same pattern as other session notifications like [`available_commands_update`](../slash-commands) and [`current_mode_update`](../session-modes).
+Agents can update session metadata in real-time by sending a `session_info_update` notification via `session/update`. This follows the same pattern as other session notifications like [`available_commands_update`](./slash-commands) and [`current_mode_update`](./session-modes).
 
 ```json
 {
@@ -187,15 +187,15 @@ All fields are optional. Only include fields that have changed — omitted field
 </ResponseField>
 
 <ResponseField name="_meta" type="object">
-  Agent-specific metadata. See [Extensibility](../extensibility).
+  Agent-specific metadata. See [Extensibility](./extensibility).
 </ResponseField>
 
-The `sessionId` and `cwd` fields are **not** included in the update — `sessionId` is already in the notification's `params`, and `cwd` is immutable (set during [`session/new`](../session-setup#creating-a-session)). Agents typically send this notification after the first meaningful exchange to auto-generate a title.
+The `sessionId` and `cwd` fields are **not** included in the update — `sessionId` is already in the notification's `params`, and `cwd` is immutable (set during [`session/new`](./session-setup#creating-a-session)). Agents typically send this notification after the first meaningful exchange to auto-generate a title.
 
 ## Interaction with Other Session Methods
 
 `session/list` is a discovery mechanism only — it does **not** restore or modify sessions:
 
 1. Client calls `session/list` to discover available sessions
 2. User selects a session from the list
-3. Client calls [`session/load`](../session-setup#loading-sessions) with the chosen `sessionId` to resume the conversation
+3. Client calls [`session/load`](./session-setup#loading-sessions) with the chosen `sessionId` to resume the conversation

docs/rfds/session-list.mdx

@@ -208,7 +208,7 @@ Agents that implement this feature gain:
 ### Compatibility Considerations
 
 - **Backward compatible**: Existing agents continue working without implementing this
-- **Capability-based**: Clients check for `listSessions` capability before using
+- **Capability-based**: Clients check for `sessionCapabilities.list` capability before using
 - **No breaking changes**: No modifications to existing endpoints
 
 ### Security Considerations