feat(unstable-v2): require more session methods by default

agent-client-protocol-schema/src/v2/conversion.rs

@@ -4963,30 +4963,26 @@ impl super::SessionCapabilities {
         let Self {
             prompt,
             mcp,
-            load,
-            list,
             delete,
             additional_directories,
             #[cfg(feature = "unstable_session_fork")]
             fork,
-            resume,
-            close,
             meta,
         } = self;
 
         Ok(V1SessionCapabilityParts {
             session_capabilities: crate::v1::SessionCapabilities {
-                list: into_v1_default_on_error(list),
+                list: Some(crate::v1::SessionListCapabilities::new()),
                 delete: into_v1_default_on_error(delete),
                 additional_directories: into_v1_default_on_error(additional_directories),
                 #[cfg(feature = "unstable_session_fork")]
                 fork: into_v1_default_on_error(fork),
-                resume: into_v1_default_on_error(resume),
-                close: into_v1_default_on_error(close),
+                resume: Some(crate::v1::SessionResumeCapabilities::new()),
+                close: Some(crate::v1::SessionCloseCapabilities::new()),
                 meta: meta.into_v1()?,
             },
             prompt_capabilities: prompt.unwrap_or_default().into_v1()?,
-            load_session: load.is_some(),
+            load_session: true,
             mcp_capabilities: mcp.unwrap_or_default().into_v1()?,
         })
     }
@@ -5001,53 +4997,27 @@ impl super::SessionCapabilities {
     pub fn from_v1(
         session_capabilities: crate::v1::SessionCapabilities,
         prompt_capabilities: crate::v1::PromptCapabilities,
-        load_session: bool,
+        _load_session: bool,
         mcp_capabilities: crate::v1::McpCapabilities,
     ) -> Result<Self> {
         let crate::v1::SessionCapabilities {
-            list,
+            list: _,
             delete,
             additional_directories,
             #[cfg(feature = "unstable_session_fork")]
             fork,
-            resume,
-            close,
+            resume: _,
+            close: _,
             meta,
         } = session_capabilities;
 
         Ok(super::SessionCapabilities {
             prompt: Some(prompt_capabilities.into_v2()?),
             mcp: Some(mcp_capabilities.into_v2()?),
-            load: load_session.then(super::SessionLoadCapabilities::new),
-            list: into_v2_default_on_error(list),
             delete: into_v2_default_on_error(delete),
             additional_directories: into_v2_default_on_error(additional_directories),
             #[cfg(feature = "unstable_session_fork")]
             fork: into_v2_default_on_error(fork),
-            resume: into_v2_default_on_error(resume),
-            close: into_v2_default_on_error(close),
-            meta: meta.into_v2()?,
-        })
-    }
-}
-
-impl IntoV1 for super::SessionListCapabilities {
-    type Output = crate::v1::SessionListCapabilities;
-
-    fn into_v1(self) -> Result<Self::Output> {
-        let Self { meta } = self;
-        Ok(crate::v1::SessionListCapabilities {
-            meta: meta.into_v1()?,
-        })
-    }
-}
-
-impl IntoV2 for crate::v1::SessionListCapabilities {
-    type Output = super::SessionListCapabilities;
-
-    fn into_v2(self) -> Result<Self::Output> {
-        let Self { meta } = self;
-        Ok(super::SessionListCapabilities {
             meta: meta.into_v2()?,
         })
     }
@@ -5120,50 +5090,6 @@ impl IntoV2 for crate::v1::SessionForkCapabilities {
     }
 }
 
-impl IntoV1 for super::SessionResumeCapabilities {
-    type Output = crate::v1::SessionResumeCapabilities;
-
-    fn into_v1(self) -> Result<Self::Output> {
-        let Self { meta } = self;
-        Ok(crate::v1::SessionResumeCapabilities {
-            meta: meta.into_v1()?,
-        })
-    }
-}
-
-impl IntoV2 for crate::v1::SessionResumeCapabilities {
-    type Output = super::SessionResumeCapabilities;
-
-    fn into_v2(self) -> Result<Self::Output> {
-        let Self { meta } = self;
-        Ok(super::SessionResumeCapabilities {
-            meta: meta.into_v2()?,
-        })
-    }
-}
-
-impl IntoV1 for super::SessionCloseCapabilities {
-    type Output = crate::v1::SessionCloseCapabilities;
-
-    fn into_v1(self) -> Result<Self::Output> {
-        let Self { meta } = self;
-        Ok(crate::v1::SessionCloseCapabilities {
-            meta: meta.into_v1()?,
-        })
-    }
-}
-
-impl IntoV2 for crate::v1::SessionCloseCapabilities {
-    type Output = super::SessionCloseCapabilities;
-
-    fn into_v2(self) -> Result<Self::Output> {
-        let Self { meta } = self;
-        Ok(super::SessionCloseCapabilities {
-            meta: meta.into_v2()?,
-        })
-    }
-}
-
 impl IntoV1 for super::PromptCapabilities {
     type Output = crate::v1::PromptCapabilities;
 
@@ -9274,9 +9200,15 @@ mod tests {
 
     #[test]
     fn round_trips_initialize_response() {
+        let session_capabilities = v1::SessionCapabilities::new()
+            .list(v1::SessionListCapabilities::new())
+            .resume(v1::SessionResumeCapabilities::new())
+            .close(v1::SessionCloseCapabilities::new());
         let response = v1::InitializeResponse::new(ProtocolVersion::V1)
             .agent_capabilities(
                 v1::AgentCapabilities::new()
+                    .load_session(true)
+                    .session_capabilities(session_capabilities)
                     .auth(v1::AgentAuthCapabilities::new().logout(v1::LogoutCapabilities::new())),
             )
             .agent_info(v1::Implementation::new("test-agent", "2.0.0").title("Test Agent"));
@@ -9293,7 +9225,7 @@ mod tests {
     }
 
     #[test]
-    fn agent_load_session_capability_moves_between_v1_and_v2() {
+    fn required_v2_session_methods_convert_to_v1_capability_markers() {
         let v1_capabilities = v1::AgentCapabilities::new().load_session(true);
 
         let v2_capabilities: v2::AgentCapabilities =
@@ -9302,17 +9234,20 @@ mod tests {
             .session
             .as_ref()
             .expect("v1 capabilities imply v2 session support");
-        assert!(session.load.is_some());
+        assert!(session.delete.is_none());
         let v2_json = serde_json::to_value(&v2_capabilities).expect("v2 serialize");
         assert_eq!(v2_json.get("loadSession"), None);
-        assert_eq!(
-            v2_json.pointer("/session/load"),
-            Some(&serde_json::json!({}))
-        );
+        assert_eq!(v2_json.pointer("/session/load"), None);
+        assert_eq!(v2_json.pointer("/session/list"), None);
+        assert_eq!(v2_json.pointer("/session/resume"), None);
+        assert_eq!(v2_json.pointer("/session/close"), None);
 
         let v1_after: v1::AgentCapabilities =
             v2_to_v1(v2_capabilities).expect("v2 -> v1 conversion");
         assert!(v1_after.load_session);
+        assert!(v1_after.session_capabilities.list.is_some());
+        assert!(v1_after.session_capabilities.resume.is_some());
+        assert!(v1_after.session_capabilities.close.is_some());
     }
 
     #[test]
@@ -9343,14 +9278,14 @@ mod tests {
     #[test]
     fn v2_session_capabilities_convert_to_v1_agent_capability_parts() {
         let parts = v2::SessionCapabilities::new()
-            .load(v2::SessionLoadCapabilities::new())
             .prompt(v2::PromptCapabilities::new().image(v2::PromptImageCapabilities::new()))
             .mcp(v2::McpCapabilities::new().http(v2::McpHttpCapabilities::new()))
-            .list(v2::SessionListCapabilities::new())
             .into_v1()
             .expect("v2 session capabilities -> v1 parts");
 
         assert!(parts.session_capabilities.list.is_some());
+        assert!(parts.session_capabilities.resume.is_some());
+        assert!(parts.session_capabilities.close.is_some());
         assert!(parts.prompt_capabilities.image);
         assert!(parts.load_session);
         assert!(parts.mcp_capabilities.http);

docs/docs.json

@@ -200,6 +200,7 @@
                 "pages": [
                   "rfds/v2/prompt",
                   "rfds/v2/enum-variant-extension",
+                  "rfds/v2/required-session-methods",
                   "rfds/v2/client-filesystem-terminal-capabilities",
                   "rfds/v2/plan-variants",
                   "rfds/v2/tool-call-updates",

docs/protocol/v2/draft/initialization.mdx

@@ -62,8 +62,7 @@ The Agent **MUST** respond with the chosen [protocol version](#protocol-version)
         "mcp": {
           "stdio": {},
           "http": {}
-        },
-        "load": {}
+        }
       }
     },
     "info": {
@@ -119,7 +118,8 @@ The Agent **SHOULD** specify whether it supports the following capabilities:
 <ResponseField name="session" type="SessionCapabilities Object">
   The Agent supports the `session/*` method surface. Omitted or `null` means the
   Agent does not support session methods. Supplying `{}` means the Agent
-  supports the baseline session methods: `session/new`, `session/prompt`,
+  supports the baseline session methods: `session/new`, `session/load`,
+  `session/list`, `session/resume`, `session/close`, `session/prompt`,
   `session/cancel`, and `session/update`.
 </ResponseField>
 
@@ -135,9 +135,13 @@ The Agent **SHOULD** specify whether it supports the following capabilities:
 
 #### Session Capabilities
 
-Supplying `session: {}` means the Agent supports `session/new`, `session/prompt`, `session/cancel`, and `session/update`.
+Supplying `session: {}` means the Agent supports `session/new`,
+`session/load`, `session/list`, `session/resume`, `session/close`,
+`session/prompt`, `session/cancel`, and `session/update`.
 
-Optionally, Agents **MAY** support prompt extensions, MCP server transports, and additional session methods by specifying nested capabilities.
+Optionally, Agents **MAY** support prompt extensions, MCP server transports, and
+additional session methods such as `session/delete` by specifying nested
+capabilities.
 
 <ResponseField name="prompt" type="PromptCapabilities Object">
   Object indicating the different types of [content](/protocol/v2/draft/content)
@@ -152,12 +156,6 @@ Optionally, Agents **MAY** support prompt extensions, MCP server transports, and
   MCP server transport support for sessions.
 </ResponseField>
 
-<ResponseField name="load" type="SessionLoadCapabilities Object">
-  The [`session/load`](/protocol/v2/draft/session-setup#loading-sessions) method
-  is available. Omitted or `null` both mean the Agent does not advertise
-  support. Supplying `{}` means the Agent supports loading sessions.
-</ResponseField>
-
 <ResponseField name="delete" type="SessionDeleteCapabilities Object">
   The [`session/delete`](/protocol/v2/draft/session-delete) method is available.
   Omitted or `null` both mean the Agent does not advertise support. Supplying an

docs/protocol/v2/draft/overview.mdx

@@ -31,7 +31,7 @@ A typical flow follows this pattern:
 <Step title="Session Setup - either:">
 
 - Client → Agent: `session/new` to create a new session
-- Client → Agent: `session/load` to resume an existing session if supported
+- Client → Agent: `session/load` or `session/resume` to resume an existing session
 
 </Step>
 
@@ -90,14 +90,34 @@ Agents are programs that use generative AI to autonomously modify code. They typ
   Agent.
 </ResponseField>
 
-### Optional Methods
-
 <ResponseField
   name="session/load"
   post={[<a href="/protocol/v2/draft/schema#session%2Fload">Schema</a>]}
 >
-  [Load an existing session](/protocol/v2/draft/session-setup#loading-sessions)
-  (requires `session.load` capability).
+  [Load an existing session](/protocol/v2/draft/session-setup#loading-sessions).
+</ResponseField>
+
+<ResponseField
+  name="session/list"
+  post={[<a href="/protocol/v2/draft/schema#session%2Flist">Schema</a>]}
+>
+  [List known sessions](/protocol/v2/draft/session-list).
+</ResponseField>
+
+<ResponseField
+  name="session/resume"
+  post={[<a href="/protocol/v2/draft/schema#session%2Fresume">Schema</a>]}
+>
+  [Resume an existing session without replaying
+  history](/protocol/v2/draft/session-setup#resuming-sessions).
+</ResponseField>
+
+<ResponseField
+  name="session/close"
+  post={[<a href="/protocol/v2/draft/schema#session%2Fclose">Schema</a>]}
+>
+  [Close an active
+  session](/protocol/v2/draft/session-setup#closing-active-sessions).
 </ResponseField>
 
 ### Notifications