diff --git a/agent-client-protocol-schema/src/v2/agent.rs b/agent-client-protocol-schema/src/v2/agent.rs index e3181db65..08efb0e15 100644 --- a/agent-client-protocol-schema/src/v2/agent.rs +++ b/agent-client-protocol-schema/src/v2/agent.rs @@ -1218,8 +1218,6 @@ impl NewSessionResponse { /// Request parameters for loading an existing session. /// -/// Only available if the Agent supports the `session.load` capability. -/// /// See protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/session-setup#loading-sessions) #[serde_as] #[skip_serializing_none] @@ -1507,9 +1505,8 @@ impl ForkSessionResponse { /// Request parameters for resuming an existing session. /// /// Resumes an existing session without returning previous messages (unlike `session/load`). -/// This is useful for agents that can resume sessions but don't implement full session loading. -/// -/// Only available if the Agent supports the `session.resume` capability. +/// This is useful when a Client already has the session history and only needs +/// to reconnect to the Agent's session state. #[serde_as] #[skip_serializing_none] #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] @@ -1642,11 +1639,9 @@ impl ResumeSessionResponse { /// Request parameters for closing an active session. /// -/// If supported, the agent **must** cancel any ongoing work related to the session -/// (treat it as if `session/cancel` was called) and then free up any resources -/// associated with the session. -/// -/// Only available if the Agent supports the `session.close` capability. +/// The agent **must** cancel any ongoing work related to the session (treat it +/// as if `session/cancel` was called) and then free up any resources associated +/// with the session. #[serde_as] #[skip_serializing_none] #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] @@ -1732,8 +1727,6 @@ impl CloseSessionResponse { // List sessions /// Request parameters for listing existing sessions. -/// -/// Only available if the Agent supports the `session.list` capability. #[serde_as] #[skip_serializing_none] #[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] @@ -4223,7 +4216,9 @@ impl ProvidersCapabilities { /// Session capabilities supported by the agent. /// /// Supplying `{}` means the agent supports the baseline session methods: -/// `session/new`, `session/prompt`, `session/cancel`, and `session/update`. +/// `session/new`, `session/load`, `session/list`, `session/resume`, +/// `session/close`, `session/prompt`, `session/cancel`, and +/// `session/update`. /// /// Agents that support sessions **MAY** support additional session methods, /// prompt content types, and MCP transports by specifying additional @@ -4253,22 +4248,6 @@ pub struct SessionCapabilities { #[schemars(extend("x-deserialize-default-on-error" = true))] #[serde(default)] pub mcp: Option, - /// Whether the agent supports `session/load`. - /// - /// Optional. Omitted or `null` both mean the agent does not advertise support. - /// Supplying `{}` means the agent supports loading sessions. - #[serde_as(deserialize_as = "DefaultOnError")] - #[schemars(extend("x-deserialize-default-on-error" = true))] - #[serde(default)] - pub load: Option, - /// Whether the agent supports `session/list`. - /// - /// Optional. Omitted or `null` both mean the agent does not advertise support. - /// Supplying `{}` means the agent supports listing sessions. - #[serde_as(deserialize_as = "DefaultOnError")] - #[schemars(extend("x-deserialize-default-on-error" = true))] - #[serde(default)] - pub list: Option, /// Whether the agent supports `session/delete`. /// /// Optional. Omitted or `null` both mean the agent does not advertise support. @@ -4283,9 +4262,8 @@ pub struct SessionCapabilities { /// Supplying `{}` means the agent supports `additionalDirectories` on /// supported session lifecycle requests. /// - /// Agents that also support `session/list` may return - /// `SessionInfo.additionalDirectories` to report the complete ordered - /// additional-root list associated with a listed session. + /// Agents may return `SessionInfo.additionalDirectories` to report the + /// complete ordered additional-root list associated with a listed session. #[serde_as(deserialize_as = "DefaultOnError")] #[schemars(extend("x-deserialize-default-on-error" = true))] #[serde(default)] @@ -4303,22 +4281,6 @@ pub struct SessionCapabilities { #[schemars(extend("x-deserialize-default-on-error" = true))] #[serde(default)] pub fork: Option, - /// Whether the agent supports `session/resume`. - /// - /// Optional. Omitted or `null` both mean the agent does not advertise support. - /// Supplying `{}` means the agent supports resuming sessions. - #[serde_as(deserialize_as = "DefaultOnError")] - #[schemars(extend("x-deserialize-default-on-error" = true))] - #[serde(default)] - pub resume: Option, - /// Whether the agent supports `session/close`. - /// - /// Optional. Omitted or `null` both mean the agent does not advertise support. - /// Supplying `{}` means the agent supports closing sessions. - #[serde_as(deserialize_as = "DefaultOnError")] - #[schemars(extend("x-deserialize-default-on-error" = true))] - #[serde(default)] - pub close: Option, /// 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. @@ -4359,26 +4321,6 @@ impl SessionCapabilities { self } - /// Whether the agent supports `session/load`. - /// - /// Omitted or `null` both mean the agent does not advertise support. - /// Supplying `{}` means the agent supports loading sessions. - #[must_use] - pub fn load(mut self, load: impl IntoOption) -> Self { - self.load = load.into_option(); - self - } - - /// Whether the agent supports `session/list`. - /// - /// Omitted or `null` both mean the agent does not advertise support. - /// Supplying `{}` means the agent supports listing sessions. - #[must_use] - pub fn list(mut self, list: impl IntoOption) -> Self { - self.list = list.into_option(); - self - } - /// Whether the agent supports `session/delete`. /// /// Omitted or `null` both mean the agent does not advertise support. @@ -4395,9 +4337,8 @@ impl SessionCapabilities { /// Supplying `{}` means the agent supports `additionalDirectories` on /// supported session lifecycle requests. /// - /// Agents that also support `session/list` may return - /// `SessionInfo.additionalDirectories` to report the complete ordered - /// additional-root list associated with a listed session. + /// Agents may return `SessionInfo.additionalDirectories` to report the + /// complete ordered additional-root list associated with a listed session. #[must_use] pub fn additional_directories( mut self, @@ -4418,104 +4359,6 @@ impl SessionCapabilities { self } - /// Whether the agent supports `session/resume`. - /// - /// Omitted or `null` both mean the agent does not advertise support. - /// Supplying `{}` means the agent supports resuming sessions. - #[must_use] - pub fn resume(mut self, resume: impl IntoOption) -> Self { - self.resume = resume.into_option(); - self - } - - /// Whether the agent supports `session/close`. - /// - /// Omitted or `null` both mean the agent does not advertise support. - /// Supplying `{}` means the agent supports closing sessions. - #[must_use] - pub fn close(mut self, close: impl IntoOption) -> Self { - self.close = close.into_option(); - self - } - - /// 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) - #[must_use] - pub fn meta(mut self, meta: impl IntoOption) -> Self { - self.meta = meta.into_option(); - self - } -} - -/// Capabilities for the `session/load` method. -/// -/// Supplying `{}` means the agent supports loading sessions. -#[serde_as] -#[skip_serializing_none] -#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] -#[non_exhaustive] -pub struct SessionLoadCapabilities { - /// 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) - #[serde_as(deserialize_as = "DefaultOnError")] - #[schemars(extend("x-deserialize-default-on-error" = true))] - #[serde(default)] - #[serde(rename = "_meta")] - pub meta: Option, -} - -impl SessionLoadCapabilities { - /// Builds an empty [`SessionLoadCapabilities`]; use builder methods to advertise supported sub-capabilities. - #[must_use] - pub fn new() -> Self { - Self::default() - } - - /// 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) - #[must_use] - pub fn meta(mut self, meta: impl IntoOption) -> Self { - self.meta = meta.into_option(); - self - } -} - -/// Capabilities for the `session/list` method. -/// -/// Supplying `{}` means the agent supports listing sessions. -#[serde_as] -#[skip_serializing_none] -#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] -#[non_exhaustive] -pub struct SessionListCapabilities { - /// 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) - #[serde_as(deserialize_as = "DefaultOnError")] - #[schemars(extend("x-deserialize-default-on-error" = true))] - #[serde(default)] - #[serde(rename = "_meta")] - pub meta: Option, -} - -impl SessionListCapabilities { - /// Builds an empty [`SessionListCapabilities`]; use builder methods to advertise supported sub-capabilities. - #[must_use] - pub fn new() -> Self { - Self::default() - } - /// 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. @@ -4654,84 +4497,6 @@ impl SessionForkCapabilities { } } -/// Capabilities for the `session/resume` method. -/// -/// Supplying `{}` means the agent supports resuming sessions. -#[serde_as] -#[skip_serializing_none] -#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] -#[non_exhaustive] -pub struct SessionResumeCapabilities { - /// 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) - #[serde_as(deserialize_as = "DefaultOnError")] - #[schemars(extend("x-deserialize-default-on-error" = true))] - #[serde(default)] - #[serde(rename = "_meta")] - pub meta: Option, -} - -impl SessionResumeCapabilities { - /// Builds an empty [`SessionResumeCapabilities`]; use builder methods to advertise supported sub-capabilities. - #[must_use] - pub fn new() -> Self { - Self::default() - } - - /// 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) - #[must_use] - pub fn meta(mut self, meta: impl IntoOption) -> Self { - self.meta = meta.into_option(); - self - } -} - -/// Capabilities for the `session/close` method. -/// -/// Supplying `{}` means the agent supports closing sessions. -#[serde_as] -#[skip_serializing_none] -#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)] -#[non_exhaustive] -pub struct SessionCloseCapabilities { - /// 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) - #[serde_as(deserialize_as = "DefaultOnError")] - #[schemars(extend("x-deserialize-default-on-error" = true))] - #[serde(default)] - #[serde(rename = "_meta")] - pub meta: Option, -} - -impl SessionCloseCapabilities { - /// Builds an empty [`SessionCloseCapabilities`]; use builder methods to advertise supported sub-capabilities. - #[must_use] - pub fn new() -> Self { - Self::default() - } - - /// 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) - #[must_use] - pub fn meta(mut self, meta: impl IntoOption) -> Self { - self.meta = meta.into_option(); - self - } -} - /// Prompt capabilities supported by the agent in `session/prompt` requests. /// /// Baseline agent functionality requires support for [`ContentBlock::Text`] @@ -5467,8 +5232,6 @@ pub enum ClientRequest { NewSessionRequest(Box), /// Loads an existing session to resume a previous conversation. /// - /// This method is only available if the agent advertises the `session.load` capability. - /// /// The agent should: /// - Restore the session context and conversation history /// - Connect to the specified MCP servers @@ -5478,8 +5241,6 @@ pub enum ClientRequest { LoadSessionRequest(Box), /// Lists existing sessions known to the agent. /// - /// This method is only available if the agent advertises the `session.list` capability. - /// /// The agent should return metadata about sessions with optional filtering and pagination support. ListSessionsRequest(Box), /// Deletes an existing session from `session/list`. @@ -5501,15 +5262,11 @@ pub enum ClientRequest { ForkSessionRequest(Box), /// Resumes an existing session without returning previous messages. /// - /// This method is only available if the agent advertises the `session.resume` capability. - /// /// The agent should resume the session context, allowing the conversation to continue /// without replaying the message history (unlike `session/load`). ResumeSessionRequest(Box), /// Closes an active session and frees up any resources associated with it. /// - /// This method is only available if the agent advertises the `session.close` capability. - /// /// The agent must cancel any ongoing work (as if `session/cancel` was called) /// and then free up any resources associated with the session. CloseSessionRequest(Box), @@ -6438,17 +6195,6 @@ mod test_serialization { Vec::::new() ); } - #[test] - fn test_session_load_capabilities_serialization() { - assert_eq!( - serde_json::to_value(SessionCapabilities::new().load(SessionLoadCapabilities::new())) - .unwrap(), - json!({ - "load": {} - }) - ); - } - #[test] fn test_session_additional_directories_capabilities_serialization() { assert_eq!( @@ -7299,8 +7045,7 @@ mod test_serialization { let caps = AgentCapabilities::new().session( SessionCapabilities::new() .prompt(PromptCapabilities::new().image(PromptImageCapabilities::new())) - .mcp(McpCapabilities::new().stdio(McpStdioCapabilities::new())) - .load(SessionLoadCapabilities::new()), + .mcp(McpCapabilities::new().stdio(McpStdioCapabilities::new())), ); assert_eq!( @@ -7312,8 +7057,7 @@ mod test_serialization { }, "mcp": { "stdio": {} - }, - "load": {} + } } }) ); diff --git a/agent-client-protocol-schema/src/v2/conversion.rs b/agent-client-protocol-schema/src/v2/conversion.rs index 72532579d..58832dc51 100644 --- a/agent-client-protocol-schema/src/v2/conversion.rs +++ b/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 { 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 { - 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 { - 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 { - 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 { - 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 { - 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 { - 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); diff --git a/docs/docs.json b/docs/docs.json index bed6252c2..9a9995f0b 100644 --- a/docs/docs.json +++ b/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", diff --git a/docs/protocol/v2/draft/initialization.mdx b/docs/protocol/v2/draft/initialization.mdx index 846647091..fededccde 100644 --- a/docs/protocol/v2/draft/initialization.mdx +++ b/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: 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`. @@ -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. 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. - - 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. - - The [`session/delete`](/protocol/v2/draft/session-delete) method is available. Omitted or `null` both mean the Agent does not advertise support. Supplying an diff --git a/docs/protocol/v2/draft/overview.mdx b/docs/protocol/v2/draft/overview.mdx index 683e06b4c..d19c878c2 100644 --- a/docs/protocol/v2/draft/overview.mdx +++ b/docs/protocol/v2/draft/overview.mdx @@ -31,7 +31,7 @@ A typical flow follows this pattern: - 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 @@ -90,14 +90,34 @@ Agents are programs that use generative AI to autonomously modify code. They typ Agent. -### Optional Methods - Schema]} > - [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). + + +Schema]} +> + [List known sessions](/protocol/v2/draft/session-list). + + +Schema]} +> + [Resume an existing session without replaying + history](/protocol/v2/draft/session-setup#resuming-sessions). + + +Schema]} +> + [Close an active + session](/protocol/v2/draft/session-setup#closing-active-sessions). ### Notifications diff --git a/docs/protocol/v2/draft/schema.mdx b/docs/protocol/v2/draft/schema.mdx index b1799c974..c07113cc5 100644 --- a/docs/protocol/v2/draft/schema.mdx +++ b/docs/protocol/v2/draft/schema.mdx @@ -918,8 +918,6 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Closes an active session and frees up any resources associated with it. -This method is only available if the agent advertises the `session.close` capability. - The agent must cancel any ongoing work (as if `session/cancel` was called) and then free up any resources associated with the session. @@ -927,11 +925,9 @@ and then free up any resources associated with the session. Request parameters for closing an active session. -If supported, the agent **must** cancel any ongoing work related to the session -(treat it as if `session/cancel` was called) and then free up any resources -associated with the session. - -Only available if the Agent supports the `session.close` capability. +The agent **must** cancel any ongoing work related to the session (treat it +as if `session/cancel` was called) and then free up any resources associated +with the session. **Type:** Object @@ -1102,16 +1098,12 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Lists existing sessions known to the agent. -This method is only available if the agent advertises the `session.list` capability. - The agent should return metadata about sessions with optional filtering and pagination support. #### ListSessionsRequest Request parameters for listing existing sessions. -Only available if the Agent supports the `session.list` capability. - **Type:** Object **Properties:** @@ -1160,8 +1152,6 @@ to fetch the next page. If absent, there are no more results. Loads an existing session to resume a previous conversation. -This method is only available if the agent advertises the `session.load` capability. - The agent should: - Restore the session context and conversation history @@ -1174,8 +1164,6 @@ See protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/v Request parameters for loading an existing session. -Only available if the Agent supports the `session.load` capability. - See protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/v2/draft/session-setup#loading-sessions) **Type:** Object @@ -1390,8 +1378,6 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Resumes an existing session without returning previous messages. -This method is only available if the agent advertises the `session.resume` capability. - The agent should resume the session context, allowing the conversation to continue without replaying the message history (unlike `session/load`). @@ -1400,9 +1386,8 @@ without replaying the message history (unlike `session/load`). Request parameters for resuming an existing session. Resumes an existing session without returning previous messages (unlike `session/load`). -This is useful for agents that can resume sessions but don't implement full session loading. - -Only available if the Agent supports the `session.resume` capability. +This is useful when a Client already has the session history and only needs +to reconnect to the Agent's session state. **Type:** Object @@ -6942,7 +6927,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d Session capabilities supported by the agent. Supplying `\{\}` means the agent supports the baseline session methods: -`session/new`, `session/prompt`, `session/cancel`, and `session/update`. +`session/new`, `session/load`, `session/list`, `session/resume`, +`session/close`, `session/prompt`, `session/cancel`, and +`session/update`. Agents that support sessions **MAY** support additional session methods, prompt content types, and MCP transports by specifying additional @@ -6969,16 +6956,8 @@ Optional. Omitted or `null` both mean the agent does not advertise support. Supplying `\{\}` means the agent supports `additionalDirectories` on supported session lifecycle requests. -Agents that also support `session/list` may return -`SessionInfo.additionalDirectories` to report the complete ordered -additional-root list associated with a listed session. - - -SessionCloseCapabilities | null} > - Whether the agent supports `session/close`. - -Optional. Omitted or `null` both mean the agent does not advertise support. -Supplying `\{\}` means the agent supports closing sessions. +Agents may return `SessionInfo.additionalDirectories` to report the +complete ordered additional-root list associated with a listed session. SessionDeleteCapabilities | null} > @@ -6998,20 +6977,6 @@ Whether the agent supports `session/fork`. Optional. Omitted or `null` both mean the agent does not advertise support. Supplying `\{\}` means the agent supports forking sessions. - -SessionListCapabilities | null} > - Whether the agent supports `session/list`. - -Optional. Omitted or `null` both mean the agent does not advertise support. -Supplying `\{\}` means the agent supports listing sessions. - - -SessionLoadCapabilities | null} > - Whether the agent supports `session/load`. - -Optional. Omitted or `null` both mean the agent does not advertise support. -Supplying `\{\}` means the agent supports loading sessions. - McpCapabilities | null} > MCP capabilities supported by the agent for session lifecycle requests. @@ -7027,32 +6992,6 @@ Optional. Omitted or `null` both mean the agent does not advertise any prompt extensions beyond the baseline text and resource-link content required by `session/prompt`. - -SessionResumeCapabilities | null} > - Whether the agent supports `session/resume`. - -Optional. Omitted or `null` both mean the agent does not advertise support. -Supplying `\{\}` means the agent supports resuming sessions. - - - -## SessionCloseCapabilities - -Capabilities for the `session/close` method. - -Supplying `\{\}` means the agent supports closing sessions. - -**Type:** Object - -**Properties:** - - - 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/v2/draft/extensibility) - ## SessionConfigBoolean @@ -7437,63 +7376,6 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d ISO 8601 timestamp of last activity. Set to null to clear. -## SessionListCapabilities - -Capabilities for the `session/list` method. - -Supplying `\{\}` means the agent supports listing sessions. - -**Type:** Object - -**Properties:** - - - 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/v2/draft/extensibility) - - - -## SessionLoadCapabilities - -Capabilities for the `session/load` method. - -Supplying `\{\}` means the agent supports loading sessions. - -**Type:** Object - -**Properties:** - - - 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/v2/draft/extensibility) - - - -## SessionResumeCapabilities - -Capabilities for the `session/resume` method. - -Supplying `\{\}` means the agent supports resuming sessions. - -**Type:** Object - -**Properties:** - - - 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/v2/draft/extensibility) - - - ## SessionUpdate Different types of updates that can be sent during session processing. diff --git a/docs/protocol/v2/draft/session-list.mdx b/docs/protocol/v2/draft/session-list.mdx index f5e662c71..68f01a678 100644 --- a/docs/protocol/v2/draft/session-list.mdx +++ b/docs/protocol/v2/draft/session-list.mdx @@ -7,7 +7,7 @@ The `session/list` method allows Clients to discover sessions known to an Agent. 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](/protocol/v2/draft/initialization) phase to verify the Agent supports this capability. +Before listing sessions, Clients **MUST** first complete the [initialization](/protocol/v2/draft/initialization) phase. Agents that support the `session` method surface **MUST** support `session/list`.
@@ -32,27 +32,6 @@ sequenceDiagram
-## Checking Support - -Before attempting to list sessions, Clients **MUST** verify that the Agent supports this capability by checking the `session.list` field in the `initialize` response: - -```json highlight={7-9} -{ - "jsonrpc": "2.0", - "id": 0, - "result": { - "protocolVersion": 2, - "capabilities": { - "session": { - "list": {} - } - } - } -} -``` - -If `session.list` is not present, the Agent does not support listing sessions and Clients **MUST NOT** attempt to call `session/list`. - Agents that also advertise `session.additionalDirectories` may include `additionalDirectories` in returned `SessionInfo` objects to report additional workspace roots for listed sessions. diff --git a/docs/protocol/v2/draft/session-setup.mdx b/docs/protocol/v2/draft/session-setup.mdx index e729a9523..af4f65704 100644 --- a/docs/protocol/v2/draft/session-setup.mdx +++ b/docs/protocol/v2/draft/session-setup.mdx @@ -85,30 +85,10 @@ The Agent **MUST** respond with a unique [Session ID](#session-id) that identifi ## Loading Sessions -Agents that support the `session.load` capability allow Clients to resume previous conversations with history replay. This feature enables persistence across restarts and sharing sessions between different Client instances. - -### Checking Support - -Before attempting to load a session, Clients **MUST** verify that the Agent supports this capability by checking the `session.load` field in the `initialize` response: - -```json highlight={7} -{ - "jsonrpc": "2.0", - "id": 0, - "result": { - "protocolVersion": 2, - "capabilities": { - "session": { - "load": {} - } - } - } -} -``` - -If `session.load` is omitted or `null`, the Agent does not support loading sessions and Clients **MUST NOT** attempt to call `session/load`. - -### Loading a Session +Agents that support the `session` method surface **MUST** support +`session/load`, allowing Clients to resume previous conversations with history +replay. This feature enables persistence across restarts and sharing sessions +between different Client instances. To load an existing session, Clients **MUST** call the `session/load` method with: @@ -206,34 +186,9 @@ interrupted. ## Resuming Sessions -Agents that advertise `session.resume` allow Clients to reconnect to -an existing session without replaying the conversation history. - -### Checking Support - -Before attempting to resume a session, Clients **MUST** verify that the Agent -supports this capability by checking for the `session.resume` field -in the `initialize` response: - -```json highlight={7-9} -{ - "jsonrpc": "2.0", - "id": 0, - "result": { - "protocolVersion": 2, - "capabilities": { - "session": { - "resume": {} - } - } - } -} -``` - -If `session.resume` is not present, the Agent does not support -resuming sessions and Clients **MUST NOT** attempt to call `session/resume`. - -### Resuming a Session +Agents that support the `session` method surface **MUST** support +`session/resume`, allowing Clients to reconnect to an existing session without +replaying the conversation history. To resume an existing session without replaying prior messages, Clients **MUST** call the `session/resume` method with: @@ -281,35 +236,9 @@ feature is supported by the Agent. ## Closing Active Sessions -Agents that advertise `session.close` allow Clients to tell the -Agent to cancel any ongoing work for a session and free any resources -associated with that active session. - -### Checking Support - -Before attempting to close a session, Clients **MUST** verify that the Agent -supports this capability by checking the `session.close` field in -the `initialize` response: - -```json highlight={7-9} -{ - "jsonrpc": "2.0", - "id": 0, - "result": { - "protocolVersion": 2, - "capabilities": { - "session": { - "close": {} - } - } - } -} -``` - -If `session.close` is not present, the Agent does not support -closing sessions and Clients **MUST NOT** attempt to call `session/close`. - -### Closing a Session +Agents that support the `session` method surface **MUST** support +`session/close`, allowing Clients to tell the Agent to cancel any ongoing work +for a session and free any resources associated with that active session. To close an active session, Clients **MUST** call the `session/close` method with the session ID: @@ -386,9 +315,9 @@ Clients use this ID to: - Send prompt requests via `session/prompt` - Cancel ongoing operations via `session/cancel` -- Load previous sessions via `session/load` (if the Agent supports the `session.load` capability) -- Resume previous sessions via `session/resume` (if the Agent supports the `session.resume` capability) -- Close active sessions via `session/close` (if the Agent supports the `session.close` capability) +- Load previous sessions via `session/load` +- Resume previous sessions via `session/resume` +- Close active sessions via `session/close` ## Working Directory diff --git a/docs/protocol/v2/initialization.mdx b/docs/protocol/v2/initialization.mdx index cd587ecac..563d9aedd 100644 --- a/docs/protocol/v2/initialization.mdx +++ b/docs/protocol/v2/initialization.mdx @@ -62,8 +62,7 @@ The Agent **MUST** respond with the chosen [protocol version](#protocol-version) "mcp": { "stdio": {}, "http": {} - }, - "load": {} + } } }, "info": { @@ -120,7 +119,8 @@ The Agent **SHOULD** specify whether it supports the following capabilities: 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`. @@ -130,9 +130,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. Object indicating the different types of [content](/protocol/v2/content) that @@ -147,12 +151,6 @@ Optionally, Agents **MAY** support prompt extensions, MCP server transports, and MCP server transport support for sessions. - - The [`session/load`](/protocol/v2/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. - - The [`session/delete`](/protocol/v2/session-delete) method is available. Omitted or `null` both mean the Agent does not advertise support. Supplying an diff --git a/docs/protocol/v2/overview.mdx b/docs/protocol/v2/overview.mdx index 0d728de90..e7f632f93 100644 --- a/docs/protocol/v2/overview.mdx +++ b/docs/protocol/v2/overview.mdx @@ -31,7 +31,7 @@ A typical flow follows this pattern: - 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 @@ -89,14 +89,33 @@ Agents are programs that use generative AI to autonomously modify code. They typ Agent. -### Optional Methods - Schema]} > - [Load an existing session](/protocol/v2/session-setup#loading-sessions) - (requires `session.load` capability). + [Load an existing session](/protocol/v2/session-setup#loading-sessions). + + +Schema]} +> + [List known sessions](/protocol/v2/session-list). + + +Schema]} +> + [Resume an existing session without replaying + history](/protocol/v2/session-setup#resuming-sessions). + + +Schema]} +> + [Close an active session](/protocol/v2/session-setup#closing-active-sessions). ### Notifications diff --git a/docs/protocol/v2/schema.mdx b/docs/protocol/v2/schema.mdx index f5778e734..ed546af5b 100644 --- a/docs/protocol/v2/schema.mdx +++ b/docs/protocol/v2/schema.mdx @@ -245,8 +245,6 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Closes an active session and frees up any resources associated with it. -This method is only available if the agent advertises the `session.close` capability. - The agent must cancel any ongoing work (as if `session/cancel` was called) and then free up any resources associated with the session. @@ -254,11 +252,9 @@ and then free up any resources associated with the session. Request parameters for closing an active session. -If supported, the agent **must** cancel any ongoing work related to the session -(treat it as if `session/cancel` was called) and then free up any resources -associated with the session. - -Only available if the Agent supports the `session.close` capability. +The agent **must** cancel any ongoing work related to the session (treat it +as if `session/cancel` was called) and then free up any resources associated +with the session. **Type:** Object @@ -344,16 +340,12 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Lists existing sessions known to the agent. -This method is only available if the agent advertises the `session.list` capability. - The agent should return metadata about sessions with optional filtering and pagination support. #### ListSessionsRequest Request parameters for listing existing sessions. -Only available if the Agent supports the `session.list` capability. - **Type:** Object **Properties:** @@ -402,8 +394,6 @@ to fetch the next page. If absent, there are no more results. Loads an existing session to resume a previous conversation. -This method is only available if the agent advertises the `session.load` capability. - The agent should: - Restore the session context and conversation history @@ -416,8 +406,6 @@ See protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/v Request parameters for loading an existing session. -Only available if the Agent supports the `session.load` capability. - See protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/v2/session-setup#loading-sessions) **Type:** Object @@ -632,8 +620,6 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Resumes an existing session without returning previous messages. -This method is only available if the agent advertises the `session.resume` capability. - The agent should resume the session context, allowing the conversation to continue without replaying the message history (unlike `session/load`). @@ -642,9 +628,8 @@ without replaying the message history (unlike `session/load`). Request parameters for resuming an existing session. Resumes an existing session without returning previous messages (unlike `session/load`). -This is useful for agents that can resume sessions but don't implement full session loading. - -Only available if the Agent supports the `session.resume` capability. +This is useful when a Client already has the session history and only needs +to reconnect to the Agent's session state. **Type:** Object @@ -3020,7 +3005,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e Session capabilities supported by the agent. Supplying `\{\}` means the agent supports the baseline session methods: -`session/new`, `session/prompt`, `session/cancel`, and `session/update`. +`session/new`, `session/load`, `session/list`, `session/resume`, +`session/close`, `session/prompt`, `session/cancel`, and +`session/update`. Agents that support sessions **MAY** support additional session methods, prompt content types, and MCP transports by specifying additional @@ -3047,16 +3034,8 @@ Optional. Omitted or `null` both mean the agent does not advertise support. Supplying `\{\}` means the agent supports `additionalDirectories` on supported session lifecycle requests. -Agents that also support `session/list` may return -`SessionInfo.additionalDirectories` to report the complete ordered -additional-root list associated with a listed session. - - -SessionCloseCapabilities | null} > - Whether the agent supports `session/close`. - -Optional. Omitted or `null` both mean the agent does not advertise support. -Supplying `\{\}` means the agent supports closing sessions. +Agents may return `SessionInfo.additionalDirectories` to report the +complete ordered additional-root list associated with a listed session. SessionDeleteCapabilities | null} > @@ -3065,20 +3044,6 @@ Supplying `\{\}` means the agent supports closing sessions. Optional. Omitted or `null` both mean the agent does not advertise support. Supplying `\{\}` means the agent supports deleting sessions from `session/list`. - -SessionListCapabilities | null} > - Whether the agent supports `session/list`. - -Optional. Omitted or `null` both mean the agent does not advertise support. -Supplying `\{\}` means the agent supports listing sessions. - - -SessionLoadCapabilities | null} > - Whether the agent supports `session/load`. - -Optional. Omitted or `null` both mean the agent does not advertise support. -Supplying `\{\}` means the agent supports loading sessions. - McpCapabilities | null} > MCP capabilities supported by the agent for session lifecycle requests. @@ -3094,32 +3059,6 @@ Optional. Omitted or `null` both mean the agent does not advertise any prompt extensions beyond the baseline text and resource-link content required by `session/prompt`. - -SessionResumeCapabilities | null} > - Whether the agent supports `session/resume`. - -Optional. Omitted or `null` both mean the agent does not advertise support. -Supplying `\{\}` means the agent supports resuming sessions. - - - -## SessionCloseCapabilities - -Capabilities for the `session/close` method. - -Supplying `\{\}` means the agent supports closing sessions. - -**Type:** Object - -**Properties:** - - - 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/v2/extensibility) - ## SessionConfigGroupId @@ -3446,63 +3385,6 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e ISO 8601 timestamp of last activity. Set to null to clear. -## SessionListCapabilities - -Capabilities for the `session/list` method. - -Supplying `\{\}` means the agent supports listing sessions. - -**Type:** Object - -**Properties:** - - - 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/v2/extensibility) - - - -## SessionLoadCapabilities - -Capabilities for the `session/load` method. - -Supplying `\{\}` means the agent supports loading sessions. - -**Type:** Object - -**Properties:** - - - 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/v2/extensibility) - - - -## SessionResumeCapabilities - -Capabilities for the `session/resume` method. - -Supplying `\{\}` means the agent supports resuming sessions. - -**Type:** Object - -**Properties:** - - - 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/v2/extensibility) - - - ## SessionUpdate Different types of updates that can be sent during session processing. diff --git a/docs/protocol/v2/session-list.mdx b/docs/protocol/v2/session-list.mdx index 8eb5b4e67..dc2aaefbf 100644 --- a/docs/protocol/v2/session-list.mdx +++ b/docs/protocol/v2/session-list.mdx @@ -7,7 +7,7 @@ The `session/list` method allows Clients to discover sessions known to an Agent. 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](/protocol/v2/initialization) phase to verify the Agent supports this capability. +Before listing sessions, Clients **MUST** first complete the [initialization](/protocol/v2/initialization) phase. Agents that support the `session` method surface **MUST** support `session/list`.
@@ -32,27 +32,6 @@ sequenceDiagram
-## Checking Support - -Before attempting to list sessions, Clients **MUST** verify that the Agent supports this capability by checking the `session.list` field in the `initialize` response: - -```json highlight={7-9} -{ - "jsonrpc": "2.0", - "id": 0, - "result": { - "protocolVersion": 2, - "capabilities": { - "session": { - "list": {} - } - } - } -} -``` - -If `session.list` is not present, the Agent does not support listing sessions and Clients **MUST NOT** attempt to call `session/list`. - Agents that also advertise `session.additionalDirectories` may include `additionalDirectories` in returned `SessionInfo` objects to report additional workspace roots for listed sessions. diff --git a/docs/protocol/v2/session-setup.mdx b/docs/protocol/v2/session-setup.mdx index 0d5b498ec..98ab83327 100644 --- a/docs/protocol/v2/session-setup.mdx +++ b/docs/protocol/v2/session-setup.mdx @@ -83,30 +83,10 @@ The Agent **MUST** respond with a unique [Session ID](#session-id) that identifi ## Loading Sessions -Agents that support the `session.load` capability allow Clients to resume previous conversations. This feature enables persistence across restarts and sharing sessions between different Client instances. - -### Checking Support - -Before attempting to load a session, Clients **MUST** verify that the Agent supports this capability by checking the `session.load` field in the `initialize` response: - -```json highlight={7} -{ - "jsonrpc": "2.0", - "id": 0, - "result": { - "protocolVersion": 2, - "capabilities": { - "session": { - "load": {} - } - } - } -} -``` - -If `session.load` is omitted or `null`, the Agent does not support loading sessions and Clients **MUST NOT** attempt to call `session/load`. - -### Loading a Session +Agents that support the `session` method surface **MUST** support +`session/load`, allowing Clients to resume previous conversations. This feature +enables persistence across restarts and sharing sessions between different +Client instances. To load an existing session, Clients **MUST** call the `session/load` method with: @@ -191,38 +171,20 @@ When **all** the conversation entries have been reported to the Client, the Agen { "jsonrpc": "2.0", "id": 1, - "result": null + "result": {} } ``` +The response **MAY** also include initial session configuration state when that +feature is supported by the Agent. + The Client can then continue sending prompts as if the session was never interrupted. ## Resuming Sessions -Agents that advertise `session.resume` allow Clients to reconnect to an existing session without replaying the conversation history. - -### Checking Support - -Before attempting to resume a session, Clients **MUST** verify that the Agent supports this capability by checking for the `session.resume` field in the `initialize` response: - -```json highlight={7-9} -{ - "jsonrpc": "2.0", - "id": 0, - "result": { - "protocolVersion": 2, - "capabilities": { - "session": { - "resume": {} - } - } - } -} -``` - -If `session.resume` is not present, the Agent does not support resuming sessions and Clients **MUST NOT** attempt to call `session/resume`. - -### Resuming a Session +Agents that support the `session` method surface **MUST** support +`session/resume`, allowing Clients to reconnect to an existing session without +replaying the conversation history. To resume an existing session without replaying prior messages, Clients **MUST** call the `session/resume` method with: @@ -266,30 +228,9 @@ feature is supported by the Agent. ## Closing Active Sessions -Agents that advertise `session.close` allow Clients to tell the Agent to cancel any ongoing work for a session and free any resources associated with that active session. - -### Checking Support - -Before attempting to close a session, Clients **MUST** verify that the Agent supports this capability by checking the `session.close` field in the `initialize` response: - -```json highlight={7-9} -{ - "jsonrpc": "2.0", - "id": 0, - "result": { - "protocolVersion": 2, - "capabilities": { - "session": { - "close": {} - } - } - } -} -``` - -If `session.close` is not present, the Agent does not support closing sessions and Clients **MUST NOT** attempt to call `session/close`. - -### Closing a Session +Agents that support the `session` method surface **MUST** support +`session/close`, allowing Clients to tell the Agent to cancel any ongoing work +for a session and free any resources associated with that active session. To close an active session, Clients **MUST** call the `session/close` method with the session ID: @@ -362,9 +303,9 @@ Clients use this ID to: - Send prompt requests via `session/prompt` - Cancel ongoing operations via `session/cancel` -- Load previous sessions via `session/load` (if the Agent supports the `session.load` capability) -- Resume previous sessions via `session/resume` (if the Agent supports the `session.resume` capability) -- Close active sessions via `session/close` (if the Agent supports the `session.close` capability) +- Load previous sessions via `session/load` +- Resume previous sessions via `session/resume` +- Close active sessions via `session/close` ## Working Directory diff --git a/docs/rfds/v2/overview.mdx b/docs/rfds/v2/overview.mdx index 64f831bec..060fc2c30 100644 --- a/docs/rfds/v2/overview.mdx +++ b/docs/rfds/v2/overview.mdx @@ -30,6 +30,7 @@ Current RFDs accepted as Drafts that are targeting v2 release - [New Prompt Lifecycle](./prompt.mdx) - [Enum Variant Extension](./enum-variant-extension.mdx) +- [Required Session Methods](./required-session-methods.mdx) - [Client Filesystem and Terminal Surface](./client-filesystem-terminal-capabilities.mdx) - [Plan Variants](./plan-variants.mdx) - [Tool Call Updates](./tool-call-updates.mdx) @@ -57,7 +58,8 @@ Other RFDs will progress separately and are not dependent on breaking changes (s - Group authentication methods under `auth/*`: v2 uses `auth/login` and `auth/logout` instead of v1's top-level `authenticate` and `logout` method names. `auth/logout` is required for v2 Agents and no longer uses a `capabilities.auth.logout` support marker. The generated request and response type names follow the grouped method naming as `LoginAuthRequest` / `LoginAuthResponse` and `LogoutAuthRequest` / `LogoutAuthResponse`. - Use concise capability group names such as `session` and `auth`, replacing names like `sessionCapabilities`. - Make `session` optional so non-session agents, such as NES-only agents, can omit it. - - Move session-scoped capability groups under `session`, including `prompt`, `mcp`, and `loadSession` as `session.prompt`, `session.mcp`, and `session.load`. + - Require the baseline session lifecycle methods when `session` is present: `session/new`, `session/load`, `session/list`, `session/resume`, `session/close`, `session/prompt`, `session/cancel`, and `session/update`. + - Move optional session-scoped capability groups under `session`, including `prompt` and `mcp` as `session.prompt` and `session.mcp`. - Represent support markers as capability objects instead of booleans. Supplying `{}` means supported, while omission or `null` means unsupported. Booleans remain appropriate for actual data or configuration inside an already-advertised capability. - Align MCP server transports with the current MCP transport model: - Remove the deprecated HTTP+SSE MCP transport from v2. @@ -70,15 +72,9 @@ Other RFDs will progress separately and are not dependent on breaking changes (s Changes under consideration that still need to be drafted or moved to draft: -- Capabilities: decide whether any additional capability groups should become required. - Streaming/Non-streaming consistency follow-ups: - Terminal Output type for streaming terminal output from an agent - Expand diff types (delete, move) -- session/new changes: - - Providing starting message history - - Response can provide available commands - - Potentially config options - - Get config options outside of a session (take a cwd?) - MCP: tool timeouts, more lifecycle methods ## Shiny future @@ -112,6 +108,7 @@ With the needed breaking changes, as much as possible I am targeting having a co ## Revision history - 2026-07-02: Added the v2 Permission Requests RFD for required permission titles, optional structured subjects, and tool-call permission subjects. +- 2026-07-02: Added the v2 Required Session Methods RFD and recorded that `session/load`, `session/list`, `session/resume`, and `session/close` are baseline when `session` is present. - 2026-06-30: Recorded the v2 ID unification principle: prefer domain-specific ID field names. - 2026-06-25: Recorded the v2 initialize information cleanup: required role-agnostic `info` in both params and results, replacing `clientInfo` and `agentInfo`. - 2026-06-25: Recorded the v2 authentication method cleanup: grouped `auth/login` and required `auth/logout` method names replace v1's top-level `authenticate` and capability-gated `logout`, with matching generated type names for login and logout auth requests and responses. diff --git a/docs/rfds/v2/required-session-methods.mdx b/docs/rfds/v2/required-session-methods.mdx new file mode 100644 index 000000000..118ba4fdf --- /dev/null +++ b/docs/rfds/v2/required-session-methods.mdx @@ -0,0 +1,104 @@ +--- +title: "v2 Required Session Methods" +--- + +Author(s): [@benbrandt](https://github.com/benbrandt) + +## Elevator pitch + +> What are you proposing to change? + +For ACP v2, Agents that advertise the `session` capability should be required +to support the core session lifecycle methods: `session/load`, `session/list`, +`session/resume`, and `session/close`. + +These methods should no longer have individual v2 capability markers. The +presence of `capabilities.session` should be enough for Clients to rely on the +baseline session surface. + +## Status quo + +> How do things work today and what problems does this cause? Why would we change things? + +In v1, several session lifecycle methods were added as optional capabilities: +`loadSession`, `sessionCapabilities.list`, `sessionCapabilities.resume`, and +`sessionCapabilities.close`. + +For v2, we can set a cleaner baseline. If an Agent supports sessions, it should +support the lifecycle operations needed to create, discover, reconnect, load, +prompt, cancel, update, and close them. + +In practice, almost all agents, especially the most popular ones, already support these, +and we know from users that they don't want to interact without these capabilities. + +## What we propose to do about it + +> What are you proposing to improve the situation? + +When an Agent includes `capabilities.session` in its v2 `initialize` response, +the Agent **MUST** support these baseline session methods: + +- `session/new` +- `session/load` +- `session/list` +- `session/resume` +- `session/close` +- `session/prompt` +- `session/cancel` +- `session/update` + +The v2 schema should remove the optional `session.load`, `session.list`, +`session.resume`, and `session.close` capability fields. + +The remaining optional session capabilities continue to represent optional +features: + +- `session.prompt` advertises prompt content extensions beyond the baseline. +- `session.mcp` advertises supported MCP server transports. +- `session.delete` advertises support for deleting sessions from future + `session/list` results. +- `session.additionalDirectories` advertises support for extra workspace roots + on supported session lifecycle requests. +- `session.fork` remains an unstable optional capability while the Session Fork + RFD is in progress. + +## Shiny future + +> How will things play out once this feature exists? + +Clients targeting v2 can treat `capabilities.session` as the single signal for +the baseline session surface. This makes session history, reconnection, replay, +and cleanup flows simpler to implement and less surprising for users. + +Agents that do not support sessions can still omit `capabilities.session` +entirely, preserving the option for non-session surfaces such as next edit +suggestions. + +## Implementation details and plan + +> Tell me more about your implementation. What is your detailed implementation plan? + +1. Remove the v2 `session.load`, `session.list`, `session.resume`, and + `session.close` capability fields and their generated support-marker types. +2. Update the v2 docs to describe these methods as baseline whenever + `capabilities.session` is present. +3. Update the v2 overview RFD and initialization docs to call out the required + session lifecycle methods. + +## Frequently asked questions + +> What questions have arisen over the course of authoring this document or during subsequent discussions? + +### Does this make sessions required for every v2 Agent? + +No. `capabilities.session` remains optional. This RFD only defines the baseline +methods required once an Agent chooses to advertise the session surface. + +### Why is `session/delete` still optional? + +`session/delete` removes a persisted session from future list results. That is a +separate storage-management operation, not part of the minimal lifecycle needed. + +## Revision history + +- 2026-07-02: Initial draft. diff --git a/schema/v2/schema.json b/schema/v2/schema.json index fd834ff72..74a61c8c3 100644 --- a/schema/v2/schema.json +++ b/schema/v2/schema.json @@ -1868,7 +1868,7 @@ } }, "SessionCapabilities": { - "description": "Session capabilities supported by the agent.\n\nSupplying `{}` means the agent supports the baseline session methods:\n`session/new`, `session/prompt`, `session/cancel`, and `session/update`.\n\nAgents that support sessions **MAY** support additional session methods,\nprompt content types, and MCP transports by specifying additional\ncapabilities.\n\nSee protocol docs: [Session Capabilities](https://agentclientprotocol.com/protocol/v2/initialization#session-capabilities)", + "description": "Session capabilities supported by the agent.\n\nSupplying `{}` means the agent supports the baseline session methods:\n`session/new`, `session/load`, `session/list`, `session/resume`,\n`session/close`, `session/prompt`, `session/cancel`, and\n`session/update`.\n\nAgents that support sessions **MAY** support additional session methods,\nprompt content types, and MCP transports by specifying additional\ncapabilities.\n\nSee protocol docs: [Session Capabilities](https://agentclientprotocol.com/protocol/v2/initialization#session-capabilities)", "type": "object", "properties": { "prompt": { @@ -1895,30 +1895,6 @@ ], "x-deserialize-default-on-error": true }, - "load": { - "description": "Whether the agent supports `session/load`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports loading sessions.", - "anyOf": [ - { - "$ref": "#/$defs/SessionLoadCapabilities" - }, - { - "type": "null" - } - ], - "x-deserialize-default-on-error": true - }, - "list": { - "description": "Whether the agent supports `session/list`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports listing sessions.", - "anyOf": [ - { - "$ref": "#/$defs/SessionListCapabilities" - }, - { - "type": "null" - } - ], - "x-deserialize-default-on-error": true - }, "delete": { "description": "Whether the agent supports `session/delete`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports deleting sessions from `session/list`.", "anyOf": [ @@ -1932,7 +1908,7 @@ "x-deserialize-default-on-error": true }, "additionalDirectories": { - "description": "Whether the agent supports `additionalDirectories` on supported session lifecycle requests.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports `additionalDirectories` on\nsupported session lifecycle requests.\n\nAgents that also support `session/list` may return\n`SessionInfo.additionalDirectories` to report the complete ordered\nadditional-root list associated with a listed session.", + "description": "Whether the agent supports `additionalDirectories` on supported session lifecycle requests.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports `additionalDirectories` on\nsupported session lifecycle requests.\n\nAgents may return `SessionInfo.additionalDirectories` to report the\ncomplete ordered additional-root list associated with a listed session.", "anyOf": [ { "$ref": "#/$defs/SessionAdditionalDirectoriesCapabilities" @@ -1943,30 +1919,6 @@ ], "x-deserialize-default-on-error": true }, - "resume": { - "description": "Whether the agent supports `session/resume`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports resuming sessions.", - "anyOf": [ - { - "$ref": "#/$defs/SessionResumeCapabilities" - }, - { - "type": "null" - } - ], - "x-deserialize-default-on-error": true - }, - "close": { - "description": "Whether the agent supports `session/close`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports closing sessions.", - "anyOf": [ - { - "$ref": "#/$defs/SessionCloseCapabilities" - }, - { - "type": "null" - } - ], - "x-deserialize-default-on-error": true - }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)", "type": ["object", "null"], @@ -2119,30 +2071,6 @@ } } }, - "SessionLoadCapabilities": { - "description": "Capabilities for the `session/load` method.\n\nSupplying `{}` means the agent supports loading sessions.", - "type": "object", - "properties": { - "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)", - "type": ["object", "null"], - "x-deserialize-default-on-error": true, - "additionalProperties": true - } - } - }, - "SessionListCapabilities": { - "description": "Capabilities for the `session/list` method.\n\nSupplying `{}` means the agent supports listing sessions.", - "type": "object", - "properties": { - "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)", - "type": ["object", "null"], - "x-deserialize-default-on-error": true, - "additionalProperties": true - } - } - }, "SessionDeleteCapabilities": { "description": "Capabilities for the `session/delete` method.\n\nSupplying `{}` means the agent supports deleting sessions from `session/list`.", "type": "object", @@ -2167,30 +2095,6 @@ } } }, - "SessionResumeCapabilities": { - "description": "Capabilities for the `session/resume` method.\n\nSupplying `{}` means the agent supports resuming sessions.", - "type": "object", - "properties": { - "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)", - "type": ["object", "null"], - "x-deserialize-default-on-error": true, - "additionalProperties": true - } - } - }, - "SessionCloseCapabilities": { - "description": "Capabilities for the `session/close` method.\n\nSupplying `{}` means the agent supports closing sessions.", - "type": "object", - "properties": { - "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)", - "type": ["object", "null"], - "x-deserialize-default-on-error": true, - "additionalProperties": true - } - } - }, "AgentAuthCapabilities": { "description": "Authentication-related capabilities supported by the agent.", "type": "object", @@ -4193,7 +4097,7 @@ }, { "title": "LoadSessionRequest", - "description": "Loads an existing session to resume a previous conversation.\n\nThis method is only available if the agent advertises the `session.load` capability.\n\nThe agent should:\n- Restore the session context and conversation history\n- Connect to the specified MCP servers\n- Stream the entire conversation history back to the client via notifications\n\nSee protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/v2/session-setup#loading-sessions)", + "description": "Loads an existing session to resume a previous conversation.\n\nThe agent should:\n- Restore the session context and conversation history\n- Connect to the specified MCP servers\n- Stream the entire conversation history back to the client via notifications\n\nSee protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/v2/session-setup#loading-sessions)", "allOf": [ { "$ref": "#/$defs/LoadSessionRequest" @@ -4202,7 +4106,7 @@ }, { "title": "ListSessionsRequest", - "description": "Lists existing sessions known to the agent.\n\nThis method is only available if the agent advertises the `session.list` capability.\n\nThe agent should return metadata about sessions with optional filtering and pagination support.", + "description": "Lists existing sessions known to the agent.\n\nThe agent should return metadata about sessions with optional filtering and pagination support.", "allOf": [ { "$ref": "#/$defs/ListSessionsRequest" @@ -4220,7 +4124,7 @@ }, { "title": "ResumeSessionRequest", - "description": "Resumes an existing session without returning previous messages.\n\nThis method is only available if the agent advertises the `session.resume` capability.\n\nThe agent should resume the session context, allowing the conversation to continue\nwithout replaying the message history (unlike `session/load`).", + "description": "Resumes an existing session without returning previous messages.\n\nThe agent should resume the session context, allowing the conversation to continue\nwithout replaying the message history (unlike `session/load`).", "allOf": [ { "$ref": "#/$defs/ResumeSessionRequest" @@ -4229,7 +4133,7 @@ }, { "title": "CloseSessionRequest", - "description": "Closes an active session and frees up any resources associated with it.\n\nThis method is only available if the agent advertises the `session.close` capability.\n\nThe agent must cancel any ongoing work (as if `session/cancel` was called)\nand then free up any resources associated with the session.", + "description": "Closes an active session and frees up any resources associated with it.\n\nThe agent must cancel any ongoing work (as if `session/cancel` was called)\nand then free up any resources associated with the session.", "allOf": [ { "$ref": "#/$defs/CloseSessionRequest" @@ -4591,7 +4495,7 @@ "required": ["name", "command"] }, "LoadSessionRequest": { - "description": "Request parameters for loading an existing session.\n\nOnly available if the Agent supports the `session.load` capability.\n\nSee protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/v2/session-setup#loading-sessions)", + "description": "Request parameters for loading an existing session.\n\nSee protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/v2/session-setup#loading-sessions)", "type": "object", "properties": { "sessionId": { @@ -4636,7 +4540,7 @@ "x-method": "session/load" }, "ListSessionsRequest": { - "description": "Request parameters for listing existing sessions.\n\nOnly available if the Agent supports the `session.list` capability.", + "description": "Request parameters for listing existing sessions.", "type": "object", "properties": { "cwd": { @@ -4683,7 +4587,7 @@ "x-method": "session/delete" }, "ResumeSessionRequest": { - "description": "Request parameters for resuming an existing session.\n\nResumes an existing session without returning previous messages (unlike `session/load`).\nThis is useful for agents that can resume sessions but don't implement full session loading.\n\nOnly available if the Agent supports the `session.resume` capability.", + "description": "Request parameters for resuming an existing session.\n\nResumes an existing session without returning previous messages (unlike `session/load`).\nThis is useful when a Client already has the session history and only needs\nto reconnect to the Agent's session state.", "type": "object", "properties": { "sessionId": { @@ -4728,7 +4632,7 @@ "x-method": "session/resume" }, "CloseSessionRequest": { - "description": "Request parameters for closing an active session.\n\nIf supported, the agent **must** cancel any ongoing work related to the session\n(treat it as if `session/cancel` was called) and then free up any resources\nassociated with the session.\n\nOnly available if the Agent supports the `session.close` capability.", + "description": "Request parameters for closing an active session.\n\nThe agent **must** cancel any ongoing work related to the session (treat it\nas if `session/cancel` was called) and then free up any resources associated\nwith the session.", "type": "object", "properties": { "sessionId": { diff --git a/schema/v2/schema.unstable.json b/schema/v2/schema.unstable.json index e678a3343..2ba4f2832 100644 --- a/schema/v2/schema.unstable.json +++ b/schema/v2/schema.unstable.json @@ -3048,7 +3048,7 @@ } }, "SessionCapabilities": { - "description": "Session capabilities supported by the agent.\n\nSupplying `{}` means the agent supports the baseline session methods:\n`session/new`, `session/prompt`, `session/cancel`, and `session/update`.\n\nAgents that support sessions **MAY** support additional session methods,\nprompt content types, and MCP transports by specifying additional\ncapabilities.\n\nSee protocol docs: [Session Capabilities](https://agentclientprotocol.com/protocol/v2/draft/initialization#session-capabilities)", + "description": "Session capabilities supported by the agent.\n\nSupplying `{}` means the agent supports the baseline session methods:\n`session/new`, `session/load`, `session/list`, `session/resume`,\n`session/close`, `session/prompt`, `session/cancel`, and\n`session/update`.\n\nAgents that support sessions **MAY** support additional session methods,\nprompt content types, and MCP transports by specifying additional\ncapabilities.\n\nSee protocol docs: [Session Capabilities](https://agentclientprotocol.com/protocol/v2/draft/initialization#session-capabilities)", "type": "object", "properties": { "prompt": { @@ -3075,30 +3075,6 @@ ], "x-deserialize-default-on-error": true }, - "load": { - "description": "Whether the agent supports `session/load`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports loading sessions.", - "anyOf": [ - { - "$ref": "#/$defs/SessionLoadCapabilities" - }, - { - "type": "null" - } - ], - "x-deserialize-default-on-error": true - }, - "list": { - "description": "Whether the agent supports `session/list`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports listing sessions.", - "anyOf": [ - { - "$ref": "#/$defs/SessionListCapabilities" - }, - { - "type": "null" - } - ], - "x-deserialize-default-on-error": true - }, "delete": { "description": "Whether the agent supports `session/delete`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports deleting sessions from `session/list`.", "anyOf": [ @@ -3112,7 +3088,7 @@ "x-deserialize-default-on-error": true }, "additionalDirectories": { - "description": "Whether the agent supports `additionalDirectories` on supported session lifecycle requests.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports `additionalDirectories` on\nsupported session lifecycle requests.\n\nAgents that also support `session/list` may return\n`SessionInfo.additionalDirectories` to report the complete ordered\nadditional-root list associated with a listed session.", + "description": "Whether the agent supports `additionalDirectories` on supported session lifecycle requests.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports `additionalDirectories` on\nsupported session lifecycle requests.\n\nAgents may return `SessionInfo.additionalDirectories` to report the\ncomplete ordered additional-root list associated with a listed session.", "anyOf": [ { "$ref": "#/$defs/SessionAdditionalDirectoriesCapabilities" @@ -3135,30 +3111,6 @@ ], "x-deserialize-default-on-error": true }, - "resume": { - "description": "Whether the agent supports `session/resume`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports resuming sessions.", - "anyOf": [ - { - "$ref": "#/$defs/SessionResumeCapabilities" - }, - { - "type": "null" - } - ], - "x-deserialize-default-on-error": true - }, - "close": { - "description": "Whether the agent supports `session/close`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports closing sessions.", - "anyOf": [ - { - "$ref": "#/$defs/SessionCloseCapabilities" - }, - { - "type": "null" - } - ], - "x-deserialize-default-on-error": true - }, "_meta": { "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", "type": ["object", "null"], @@ -3335,30 +3287,6 @@ } } }, - "SessionLoadCapabilities": { - "description": "Capabilities for the `session/load` method.\n\nSupplying `{}` means the agent supports loading sessions.", - "type": "object", - "properties": { - "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", - "type": ["object", "null"], - "x-deserialize-default-on-error": true, - "additionalProperties": true - } - } - }, - "SessionListCapabilities": { - "description": "Capabilities for the `session/list` method.\n\nSupplying `{}` means the agent supports listing sessions.", - "type": "object", - "properties": { - "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", - "type": ["object", "null"], - "x-deserialize-default-on-error": true, - "additionalProperties": true - } - } - }, "SessionDeleteCapabilities": { "description": "Capabilities for the `session/delete` method.\n\nSupplying `{}` means the agent supports deleting sessions from `session/list`.", "type": "object", @@ -3395,30 +3323,6 @@ } } }, - "SessionResumeCapabilities": { - "description": "Capabilities for the `session/resume` method.\n\nSupplying `{}` means the agent supports resuming sessions.", - "type": "object", - "properties": { - "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", - "type": ["object", "null"], - "x-deserialize-default-on-error": true, - "additionalProperties": true - } - } - }, - "SessionCloseCapabilities": { - "description": "Capabilities for the `session/close` method.\n\nSupplying `{}` means the agent supports closing sessions.", - "type": "object", - "properties": { - "_meta": { - "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", - "type": ["object", "null"], - "x-deserialize-default-on-error": true, - "additionalProperties": true - } - } - }, "AgentAuthCapabilities": { "description": "Authentication-related capabilities supported by the agent.", "type": "object", @@ -7010,7 +6914,7 @@ }, { "title": "LoadSessionRequest", - "description": "Loads an existing session to resume a previous conversation.\n\nThis method is only available if the agent advertises the `session.load` capability.\n\nThe agent should:\n- Restore the session context and conversation history\n- Connect to the specified MCP servers\n- Stream the entire conversation history back to the client via notifications\n\nSee protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/v2/draft/session-setup#loading-sessions)", + "description": "Loads an existing session to resume a previous conversation.\n\nThe agent should:\n- Restore the session context and conversation history\n- Connect to the specified MCP servers\n- Stream the entire conversation history back to the client via notifications\n\nSee protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/v2/draft/session-setup#loading-sessions)", "allOf": [ { "$ref": "#/$defs/LoadSessionRequest" @@ -7019,7 +6923,7 @@ }, { "title": "ListSessionsRequest", - "description": "Lists existing sessions known to the agent.\n\nThis method is only available if the agent advertises the `session.list` capability.\n\nThe agent should return metadata about sessions with optional filtering and pagination support.", + "description": "Lists existing sessions known to the agent.\n\nThe agent should return metadata about sessions with optional filtering and pagination support.", "allOf": [ { "$ref": "#/$defs/ListSessionsRequest" @@ -7046,7 +6950,7 @@ }, { "title": "ResumeSessionRequest", - "description": "Resumes an existing session without returning previous messages.\n\nThis method is only available if the agent advertises the `session.resume` capability.\n\nThe agent should resume the session context, allowing the conversation to continue\nwithout replaying the message history (unlike `session/load`).", + "description": "Resumes an existing session without returning previous messages.\n\nThe agent should resume the session context, allowing the conversation to continue\nwithout replaying the message history (unlike `session/load`).", "allOf": [ { "$ref": "#/$defs/ResumeSessionRequest" @@ -7055,7 +6959,7 @@ }, { "title": "CloseSessionRequest", - "description": "Closes an active session and frees up any resources associated with it.\n\nThis method is only available if the agent advertises the `session.close` capability.\n\nThe agent must cancel any ongoing work (as if `session/cancel` was called)\nand then free up any resources associated with the session.", + "description": "Closes an active session and frees up any resources associated with it.\n\nThe agent must cancel any ongoing work (as if `session/cancel` was called)\nand then free up any resources associated with the session.", "allOf": [ { "$ref": "#/$defs/CloseSessionRequest" @@ -7788,7 +7692,7 @@ "required": ["name", "command"] }, "LoadSessionRequest": { - "description": "Request parameters for loading an existing session.\n\nOnly available if the Agent supports the `session.load` capability.\n\nSee protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/v2/draft/session-setup#loading-sessions)", + "description": "Request parameters for loading an existing session.\n\nSee protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/v2/draft/session-setup#loading-sessions)", "type": "object", "properties": { "sessionId": { @@ -7833,7 +7737,7 @@ "x-method": "session/load" }, "ListSessionsRequest": { - "description": "Request parameters for listing existing sessions.\n\nOnly available if the Agent supports the `session.list` capability.", + "description": "Request parameters for listing existing sessions.", "type": "object", "properties": { "cwd": { @@ -7925,7 +7829,7 @@ "x-method": "session/fork" }, "ResumeSessionRequest": { - "description": "Request parameters for resuming an existing session.\n\nResumes an existing session without returning previous messages (unlike `session/load`).\nThis is useful for agents that can resume sessions but don't implement full session loading.\n\nOnly available if the Agent supports the `session.resume` capability.", + "description": "Request parameters for resuming an existing session.\n\nResumes an existing session without returning previous messages (unlike `session/load`).\nThis is useful when a Client already has the session history and only needs\nto reconnect to the Agent's session state.", "type": "object", "properties": { "sessionId": { @@ -7970,7 +7874,7 @@ "x-method": "session/resume" }, "CloseSessionRequest": { - "description": "Request parameters for closing an active session.\n\nIf supported, the agent **must** cancel any ongoing work related to the session\n(treat it as if `session/cancel` was called) and then free up any resources\nassociated with the session.\n\nOnly available if the Agent supports the `session.close` capability.", + "description": "Request parameters for closing an active session.\n\nThe agent **must** cancel any ongoing work related to the session (treat it\nas if `session/cancel` was called) and then free up any resources associated\nwith the session.", "type": "object", "properties": { "sessionId": {