From 4d302c561bd0beb42bc6a0c3ed309bb35b80ccb8 Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Fri, 30 Oct 2026 18:38:59 +0100 Subject: [PATCH] feat(unstable): add session/set_title method Add schema support for the session-set-title RFD behind the new `unstable_session_set_title` feature, in both v1 and v2: - `session/set_title` request with a required `sessionId` and `title` - response returning the title the agent stored, which may be normalized - `sessionCapabilities.title` (v1) / `session.title` (v2) capability, renamed from `setTitle` in the RFD so later title features can extend the same object - draft overview, initialization, and error page entries --- agent-client-protocol-schema/Cargo.toml | 2 + agent-client-protocol-schema/src/v1/agent.rs | 283 +++++++++++++++++++ agent-client-protocol-schema/src/v2/agent.rs | 283 +++++++++++++++++++ docs/protocol/v1/draft/error.mdx | 1 + docs/protocol/v1/draft/initialization.mdx | 8 + docs/protocol/v1/draft/schema.mdx | 121 ++++++++ docs/protocol/v2/draft/error.mdx | 1 + docs/protocol/v2/draft/initialization.mdx | 8 + docs/protocol/v2/draft/overview.mdx | 1 + docs/protocol/v2/draft/schema.mdx | 121 ++++++++ docs/rfds/session-set-title.mdx | 11 +- schema-generator/src/main.rs | 1 + schema/v1/meta.unstable.json | 1 + schema/v1/schema.unstable.json | 88 ++++++ schema/v2/meta.unstable.json | 1 + schema/v2/schema.unstable.json | 88 ++++++ 16 files changed, 1014 insertions(+), 5 deletions(-) diff --git a/agent-client-protocol-schema/Cargo.toml b/agent-client-protocol-schema/Cargo.toml index ab37d0f81..069b643bf 100644 --- a/agent-client-protocol-schema/Cargo.toml +++ b/agent-client-protocol-schema/Cargo.toml @@ -31,6 +31,7 @@ unstable = [ "unstable_mcp_over_acp", "unstable_plan_operations", "unstable_session_fork", + "unstable_session_set_title", "unstable_session_system_prompt", "unstable_subagents", "unstable_end_turn_token_usage", @@ -43,6 +44,7 @@ unstable_llm_providers = [] unstable_mcp_over_acp = [] unstable_plan_operations = [] unstable_session_fork = [] +unstable_session_set_title = [] unstable_session_system_prompt = [] unstable_subagents = [] unstable_end_turn_token_usage = [] diff --git a/agent-client-protocol-schema/src/v1/agent.rs b/agent-client-protocol-schema/src/v1/agent.rs index 1bc75fe64..59e0175e0 100644 --- a/agent-client-protocol-schema/src/v1/agent.rs +++ b/agent-client-protocol-schema/src/v1/agent.rs @@ -1951,6 +1951,129 @@ impl SessionInfo { } } +// Set session title + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// Request parameters for setting the title of a session. +/// +/// Only available if the Agent supports the `sessionCapabilities.title` capability. +/// +/// The session does not need to be active on the connection. Any session the Agent would +/// return from `session/list` can be retitled. A session that does not exist gets `-32002`. +/// +/// The Agent responds only after it has stored the title. After a successful response, the +/// Agent SHOULD NOT replace the title with one it generates automatically. +#[cfg(feature = "unstable_session_set_title")] +#[serde_as] +#[skip_serializing_none] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_SET_TITLE_METHOD_NAME)))] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct SetSessionTitleRequest { + /// The ID of the session to retitle. + pub session_id: SessionId, + /// The new title for the session. + /// + /// Required and non-null. Omission and explicit `null` are both invalid. The Agent MAY + /// normalize the title before storing it, for example by trimming whitespace or + /// truncating it. The Agent rejects a title that fails its validation, including one + /// that is empty after normalization, with `-32602`. + pub title: String, + /// 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/v1/extensibility) + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default)] + #[serde(rename = "_meta")] + pub meta: Option, +} + +#[cfg(feature = "unstable_session_set_title")] +impl SetSessionTitleRequest { + /// Builds [`SetSessionTitleRequest`] with the required request fields set. Optional fields start unset or empty. + #[must_use] + pub fn new(session_id: impl Into, title: impl Into) -> Self { + Self { + session_id: session_id.into(), + title: title.into(), + meta: None, + } + } + + /// 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/v1/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// Response from setting the title of a session. +#[cfg(feature = "unstable_session_set_title")] +#[serde_as] +#[skip_serializing_none] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_SET_TITLE_METHOD_NAME)))] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct SetSessionTitleResponse { + /// The title the Agent stored. + /// + /// This differs from the requested title if the Agent normalized it. Clients SHOULD + /// display this value rather than the one they sent. + pub title: String, + /// 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/v1/extensibility) + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default)] + #[serde(rename = "_meta")] + pub meta: Option, +} + +#[cfg(feature = "unstable_session_set_title")] +impl SetSessionTitleResponse { + /// Builds [`SetSessionTitleResponse`] with the required response fields set. Optional fields start unset or empty. + #[must_use] + pub fn new(title: impl Into) -> Self { + Self { + title: title.into(), + meta: None, + } + } + + /// 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/v1/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + // Session modes /// The set of modes and the one currently active. @@ -4282,6 +4405,22 @@ pub struct SessionCapabilities { #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] pub fork: Option, + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// Whether the agent supports `session/set_title`. + /// + /// Agents report titles through `session/list` and `session_info_update` without this + /// capability. It only advertises that Clients can set titles. + /// + /// Optional. Omitted or `null` both mean the agent does not advertise support. + /// Supplying `{}` means the agent supports setting session titles. + #[cfg(feature = "unstable_session_set_title")] + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default)] + pub title: Option, /// Whether the agent supports `session/resume`. /// /// Optional. Omitted or `null` both mean the agent does not advertise support. @@ -4384,6 +4523,24 @@ impl SessionCapabilities { self } + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// Whether the agent supports `session/set_title`. + /// + /// Agents report titles through `session/list` and `session_info_update` without this + /// capability. It only advertises that Clients can set titles. + /// + /// Omitted or `null` both mean the agent does not advertise support. + /// Supplying `{}` means the agent supports setting session titles. + #[cfg(feature = "unstable_session_set_title")] + #[must_use] + pub fn title(mut self, title: impl IntoOption) -> Self { + self.title = title.into_option(); + self + } + /// Whether the agent supports `session/resume`. /// /// Omitted or `null` both mean the agent does not advertise support. @@ -4767,6 +4924,53 @@ impl SessionForkCapabilities { } } +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// Capabilities for Client-set session titles. +/// +/// Supplying `{}` means the agent supports `session/set_title`. Agents report titles +/// through `session/list` and `session_info_update` without this capability. +#[cfg(feature = "unstable_session_set_title")] +#[serde_as] +#[skip_serializing_none] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[non_exhaustive] +pub struct SessionTitleCapabilities { + /// 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/v1/extensibility) + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default)] + #[serde(rename = "_meta")] + pub meta: Option, +} + +#[cfg(feature = "unstable_session_set_title")] +impl SessionTitleCapabilities { + /// Builds an empty [`SessionTitleCapabilities`]. 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/v1/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + /// Capabilities for the `session/resume` method. /// /// Supplying `{}` means the agent supports resuming sessions. @@ -5067,6 +5271,9 @@ pub struct AgentMethodNames { /// Method for forking an existing session. #[cfg(feature = "unstable_session_fork")] pub session_fork: &'static str, + /// Method for setting the title of a session. + #[cfg(feature = "unstable_session_set_title")] + pub session_set_title: &'static str, /// Method for resuming an existing session. pub session_resume: &'static str, /// Method for closing an active session. @@ -5097,6 +5304,8 @@ pub const AGENT_METHOD_NAMES: AgentMethodNames = AgentMethodNames { session_delete: SESSION_DELETE_METHOD_NAME, #[cfg(feature = "unstable_session_fork")] session_fork: SESSION_FORK_METHOD_NAME, + #[cfg(feature = "unstable_session_set_title")] + session_set_title: SESSION_SET_TITLE_METHOD_NAME, session_resume: SESSION_RESUME_METHOD_NAME, session_close: SESSION_CLOSE_METHOD_NAME, logout: LOGOUT_METHOD_NAME, @@ -5134,6 +5343,9 @@ pub(crate) const SESSION_DELETE_METHOD_NAME: &str = "session/delete"; /// Method name for forking an existing session. #[cfg(feature = "unstable_session_fork")] pub(crate) const SESSION_FORK_METHOD_NAME: &str = "session/fork"; +/// Method name for setting the title of a session. +#[cfg(feature = "unstable_session_set_title")] +pub(crate) const SESSION_SET_TITLE_METHOD_NAME: &str = "session/set_title"; /// Method name for resuming an existing session. pub(crate) const SESSION_RESUME_METHOD_NAME: &str = "session/resume"; /// Method name for closing an active session. @@ -5253,6 +5465,18 @@ pub enum ClientRequest { /// set up with the request's `cwd`, `additionalDirectories`, and `mcpServers`. /// The client can prompt it without calling `session/load` or `session/resume` first. ForkSessionRequest(ForkSessionRequest), + #[cfg(feature = "unstable_session_set_title")] + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// Sets the title of a session. + /// + /// This method is only available if the agent advertises the `sessionCapabilities.title` capability. + /// + /// The session does not need to be active on the connection. The agent stores the + /// title and returns the stored title, which may be normalized. + SetSessionTitleRequest(SetSessionTitleRequest), /// Resumes an existing session without returning previous messages. /// /// This method is only available if the agent advertises the `sessionCapabilities.resume` capability. @@ -5324,6 +5548,8 @@ impl ClientRequest { Self::DeleteSessionRequest(_) => AGENT_METHOD_NAMES.session_delete, #[cfg(feature = "unstable_session_fork")] Self::ForkSessionRequest(_) => AGENT_METHOD_NAMES.session_fork, + #[cfg(feature = "unstable_session_set_title")] + Self::SetSessionTitleRequest(_) => AGENT_METHOD_NAMES.session_set_title, Self::ResumeSessionRequest(_) => AGENT_METHOD_NAMES.session_resume, Self::CloseSessionRequest(_) => AGENT_METHOD_NAMES.session_close, Self::SetSessionModeRequest(_) => AGENT_METHOD_NAMES.session_set_mode, @@ -5373,6 +5599,9 @@ pub enum AgentResponse { /// Successful result returned for a `session/fork` request. #[cfg(feature = "unstable_session_fork")] ForkSessionResponse(ForkSessionResponse), + /// Successful result returned for a `session/set_title` request. + #[cfg(feature = "unstable_session_set_title")] + SetSessionTitleResponse(SetSessionTitleResponse), /// Successful result returned for a `session/resume` request. ResumeSessionResponse(#[serde(default)] ResumeSessionResponse), /// Successful result returned for a `session/close` request. @@ -5961,6 +6190,60 @@ mod test_serialization { }) ); } + #[cfg(feature = "unstable_session_set_title")] + #[test] + fn test_session_set_title_serialization() { + assert_eq!(AGENT_METHOD_NAMES.session_set_title, "session/set_title"); + assert_eq!( + ClientRequest::SetSessionTitleRequest(SetSessionTitleRequest::new( + "sess_abc123", + "Investigate OAuth timeout" + )) + .method(), + "session/set_title" + ); + assert_eq!( + serde_json::to_value(SetSessionTitleRequest::new( + "sess_abc123", + "Investigate OAuth timeout" + )) + .unwrap(), + json!({ + "sessionId": "sess_abc123", + "title": "Investigate OAuth timeout" + }) + ); + assert_eq!( + serde_json::to_value(SetSessionTitleResponse::new("Investigate OAuth timeout")) + .unwrap(), + json!({ + "title": "Investigate OAuth timeout" + }) + ); + assert_eq!( + serde_json::to_value(SessionCapabilities::new().title(SessionTitleCapabilities::new())) + .unwrap(), + json!({ + "title": {} + }) + ); + } + + #[cfg(feature = "unstable_session_set_title")] + #[test] + fn test_session_set_title_requires_title() { + for params in [ + json!({"sessionId": "sess_abc123"}), + json!({"sessionId": "sess_abc123", "title": null}), + json!({"sessionId": "sess_abc123", "title": 42}), + ] { + assert!(serde_json::from_value::(params).is_err()); + } + for result in [json!({}), json!({"title": null})] { + assert!(serde_json::from_value::(result).is_err()); + } + } + #[test] fn test_session_additional_directories_serialization() { assert_eq!( diff --git a/agent-client-protocol-schema/src/v2/agent.rs b/agent-client-protocol-schema/src/v2/agent.rs index 8cfed3f0a..a75db54f2 100644 --- a/agent-client-protocol-schema/src/v2/agent.rs +++ b/agent-client-protocol-schema/src/v2/agent.rs @@ -2082,6 +2082,129 @@ impl SessionInfo { } } +// Set session title + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// Request parameters for setting the title of a session. +/// +/// Only available if the Agent supports the `session.title` capability. +/// +/// The session does not need to be active on the connection. Any session the Agent would +/// return from `session/list` can be retitled. A session that does not exist gets `-32002`. +/// +/// The Agent responds only after it has stored the title. After a successful response, the +/// Agent SHOULD NOT replace the title with one it generates automatically. +#[cfg(feature = "unstable_session_set_title")] +#[serde_as] +#[skip_serializing_none] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_SET_TITLE_METHOD_NAME)))] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct SetSessionTitleRequest { + /// The ID of the session to retitle. + pub session_id: SessionId, + /// The new title for the session. + /// + /// Required and non-null. Omission and explicit `null` are both invalid. The Agent MAY + /// normalize the title before storing it, for example by trimming whitespace or + /// truncating it. The Agent rejects a title that fails its validation, including one + /// that is empty after normalization, with `-32602`. + pub title: String, + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. + /// Implementations MUST NOT assign meaning to keys they do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default)] + #[serde(rename = "_meta")] + pub meta: Option, +} + +#[cfg(feature = "unstable_session_set_title")] +impl SetSessionTitleRequest { + /// Builds [`SetSessionTitleRequest`] with the required request fields set. Optional fields start unset or empty. + #[must_use] + pub fn new(session_id: impl Into, title: impl Into) -> Self { + Self { + session_id: session_id.into(), + title: title.into(), + meta: None, + } + } + + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they + /// do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// Response from setting the title of a session. +#[cfg(feature = "unstable_session_set_title")] +#[serde_as] +#[skip_serializing_none] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[cfg_attr(feature = "schemars", schemars(extend("x-side" = "agent", "x-method" = SESSION_SET_TITLE_METHOD_NAME)))] +#[serde(rename_all = "camelCase")] +#[non_exhaustive] +pub struct SetSessionTitleResponse { + /// The title the Agent stored. + /// + /// This differs from the requested title if the Agent normalized it. Clients SHOULD + /// display this value rather than the one they sent. + pub title: String, + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. + /// Implementations MUST NOT assign meaning to keys they do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default)] + #[serde(rename = "_meta")] + pub meta: Option, +} + +#[cfg(feature = "unstable_session_set_title")] +impl SetSessionTitleResponse { + /// Builds [`SetSessionTitleResponse`] with the required response fields set. Optional fields start unset or empty. + #[must_use] + pub fn new(title: impl Into) -> Self { + Self { + title: title.into(), + meta: None, + } + } + + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Implementations MUST NOT assign meaning to keys they + /// do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) + #[must_use] + pub fn meta(mut self, meta: impl IntoOption) -> Self { + self.meta = meta.into_option(); + self + } +} + // Session config options /// Unique identifier for a session configuration option. @@ -4587,6 +4710,22 @@ pub struct SessionCapabilities { #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] #[serde(default)] pub fork: Option, + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// Whether the agent supports `session/set_title`. + /// + /// Agents report titles through `session/list` and `session_info_update` without this + /// capability. It only advertises that Clients can set titles. + /// + /// Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. + /// Supplying `{}` means the agent supports setting session titles. + #[cfg(feature = "unstable_session_set_title")] + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default)] + pub title: Option, /// The _meta property is reserved by ACP to allow clients and agents to attach additional /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. /// Implementations MUST NOT assign meaning to keys they do not recognize. @@ -4683,6 +4822,24 @@ impl SessionCapabilities { self } + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// Whether the agent supports `session/set_title`. + /// + /// Agents report titles through `session/list` and `session_info_update` without this + /// capability. It only advertises that Clients can set titles. + /// + /// Omitted and `null` are equivalent and mean the agent does not advertise support. + /// Supplying `{}` means the agent supports setting session titles. + #[cfg(feature = "unstable_session_set_title")] + #[must_use] + pub fn title(mut self, title: impl IntoOption) -> Self { + self.title = title.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 assign meaning to keys they /// do not recognize. @@ -5006,6 +5163,53 @@ impl SessionForkCapabilities { } } +/// **UNSTABLE** +/// +/// This capability is not part of the spec yet, and may be removed or changed at any point. +/// +/// Capabilities for Client-set session titles. +/// +/// Supplying `{}` means the agent supports `session/set_title`. Agents report titles +/// through `session/list` and `session_info_update` without this capability. +#[cfg(feature = "unstable_session_set_title")] +#[serde_as] +#[skip_serializing_none] +#[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))] +#[derive(Default, Debug, Clone, Serialize, Deserialize, PartialEq, Eq)] +#[non_exhaustive] +pub struct SessionTitleCapabilities { + /// The _meta property is reserved by ACP to allow clients and agents to attach additional + /// metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. + /// Implementations MUST NOT assign meaning to keys they do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility) + #[serde_as(deserialize_as = "DefaultOnError")] + #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))] + #[serde(default)] + #[serde(rename = "_meta")] + pub meta: Option, +} + +#[cfg(feature = "unstable_session_set_title")] +impl SessionTitleCapabilities { + /// Builds an empty [`SessionTitleCapabilities`]. 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 assign meaning to keys they + /// do not recognize. + /// + /// See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/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 `text` @@ -5554,6 +5758,9 @@ pub struct AgentMethodNames { /// Method for forking an existing session. #[cfg(feature = "unstable_session_fork")] pub session_fork: &'static str, + /// Method for setting the title of a session. + #[cfg(feature = "unstable_session_set_title")] + pub session_set_title: &'static str, /// Method for resuming an existing session. pub session_resume: &'static str, /// Method for closing an active session. @@ -5582,6 +5789,8 @@ pub const AGENT_METHOD_NAMES: AgentMethodNames = AgentMethodNames { session_delete: SESSION_DELETE_METHOD_NAME, #[cfg(feature = "unstable_session_fork")] session_fork: SESSION_FORK_METHOD_NAME, + #[cfg(feature = "unstable_session_set_title")] + session_set_title: SESSION_SET_TITLE_METHOD_NAME, session_resume: SESSION_RESUME_METHOD_NAME, session_close: SESSION_CLOSE_METHOD_NAME, auth_logout: AUTH_LOGOUT_METHOD_NAME, @@ -5615,6 +5824,9 @@ pub(crate) const SESSION_DELETE_METHOD_NAME: &str = "session/delete"; /// Method name for forking an existing session. #[cfg(feature = "unstable_session_fork")] pub(crate) const SESSION_FORK_METHOD_NAME: &str = "session/fork"; +/// Method name for setting the title of a session. +#[cfg(feature = "unstable_session_set_title")] +pub(crate) const SESSION_SET_TITLE_METHOD_NAME: &str = "session/set_title"; /// Method name for resuming an existing session. pub(crate) const SESSION_RESUME_METHOD_NAME: &str = "session/resume"; /// Method name for closing an active session. @@ -5732,6 +5944,18 @@ pub enum ClientRequest { /// set up with the request's `cwd`, `additionalDirectories`, and `mcpServers`. /// The client can prompt it without calling `session/resume` first. ForkSessionRequest(Box), + #[cfg(feature = "unstable_session_set_title")] + /// **UNSTABLE** + /// + /// This capability is not part of the spec yet, and may be removed or changed at any point. + /// + /// Sets the title of a session. + /// + /// This method is only available if the agent advertises the `session.title` capability. + /// + /// The session does not need to be active on the connection. The agent stores the + /// title and returns the stored title, which may be normalized. + SetSessionTitleRequest(Box), /// Resumes an existing session. /// /// The agent should resume the session context, allowing the conversation @@ -5795,6 +6019,8 @@ impl ClientRequest { Self::DeleteSessionRequest(_) => AGENT_METHOD_NAMES.session_delete, #[cfg(feature = "unstable_session_fork")] Self::ForkSessionRequest(_) => AGENT_METHOD_NAMES.session_fork, + #[cfg(feature = "unstable_session_set_title")] + Self::SetSessionTitleRequest(_) => AGENT_METHOD_NAMES.session_set_title, Self::ResumeSessionRequest(_) => AGENT_METHOD_NAMES.session_resume, Self::CloseSessionRequest(_) => AGENT_METHOD_NAMES.session_close, Self::SetSessionConfigOptionRequest(_) => AGENT_METHOD_NAMES.session_set_config_option, @@ -5840,6 +6066,9 @@ pub enum AgentResponse { /// Successful result returned for a `session/fork` request. #[cfg(feature = "unstable_session_fork")] ForkSessionResponse(Box), + /// Successful result returned for a `session/set_title` request. + #[cfg(feature = "unstable_session_set_title")] + SetSessionTitleResponse(Box), /// Successful result returned for a `session/resume` request. ResumeSessionResponse(#[serde(default)] Box), /// Successful result returned for a `session/close` request. @@ -6791,6 +7020,60 @@ mod test_serialization { }) ); } + #[cfg(feature = "unstable_session_set_title")] + #[test] + fn test_session_set_title_serialization() { + assert_eq!(AGENT_METHOD_NAMES.session_set_title, "session/set_title"); + assert_eq!( + ClientRequest::SetSessionTitleRequest(Box::new(SetSessionTitleRequest::new( + "sess_abc123", + "Investigate OAuth timeout" + ))) + .method(), + "session/set_title" + ); + assert_eq!( + serde_json::to_value(SetSessionTitleRequest::new( + "sess_abc123", + "Investigate OAuth timeout" + )) + .unwrap(), + json!({ + "sessionId": "sess_abc123", + "title": "Investigate OAuth timeout" + }) + ); + assert_eq!( + serde_json::to_value(SetSessionTitleResponse::new("Investigate OAuth timeout")) + .unwrap(), + json!({ + "title": "Investigate OAuth timeout" + }) + ); + assert_eq!( + serde_json::to_value(SessionCapabilities::new().title(SessionTitleCapabilities::new())) + .unwrap(), + json!({ + "title": {} + }) + ); + } + + #[cfg(feature = "unstable_session_set_title")] + #[test] + fn test_session_set_title_requires_title() { + for params in [ + json!({"sessionId": "sess_abc123"}), + json!({"sessionId": "sess_abc123", "title": null}), + json!({"sessionId": "sess_abc123", "title": 42}), + ] { + assert!(serde_json::from_value::(params).is_err()); + } + for result in [json!({}), json!({"title": null})] { + assert!(serde_json::from_value::(result).is_err()); + } + } + #[test] fn test_session_additional_directories_serialization() { assert_eq!( diff --git a/docs/protocol/v1/draft/error.mdx b/docs/protocol/v1/draft/error.mdx index 1c45acc70..7b3eae40f 100644 --- a/docs/protocol/v1/draft/error.mdx +++ b/docs/protocol/v1/draft/error.mdx @@ -61,4 +61,5 @@ Agents **SHOULD** reject any request other than `initialize` that arrives before ## Unstable features - `session/fork` of a session that does not exist gets `-32002`, as for [unknown sessions](#unknown-sessions). +- `session/set_title` of a session that does not exist gets `-32002`. The session doesn't have to be loaded. A title the Agent rejects gets `-32602`. - A `systemPrompt` the Agent cannot apply gets an error, `-32602` recommended. See [System Prompt](/protocol/v1/draft/session-setup#system-prompt-unstable). diff --git a/docs/protocol/v1/draft/initialization.mdx b/docs/protocol/v1/draft/initialization.mdx index 6dea23013..c1dfbfc3c 100644 --- a/docs/protocol/v1/draft/initialization.mdx +++ b/docs/protocol/v1/draft/initialization.mdx @@ -313,6 +313,14 @@ Optionally, they **MAY** support other session methods and notifications by spec Supplying `{ "mode": { "override": {} } }` also advertises `override` mode. + + **Unstable.** The [`session/set_title`](/rfds/session-set-title) method is + available. Omitted or `null` both mean the Agent does not advertise support. + Supplying an empty object means Clients can set session titles. Agents report + titles through `session/list` and `session_info_update` without this + capability. + + `session/load` is still handled by the top-level `load_session` capability. This will be unified in future versions of the protocol. diff --git a/docs/protocol/v1/draft/schema.mdx b/docs/protocol/v1/draft/schema.mdx index 1e87bb1ef..50cf7f0b8 100644 --- a/docs/protocol/v1/draft/schema.mdx +++ b/docs/protocol/v1/draft/schema.mdx @@ -1241,6 +1241,89 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/d + +### session/set_title + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Sets the title of a session. + +This method is only available if the agent advertises the `sessionCapabilities.title` capability. + +The session does not need to be active on the connection. The agent stores the +title and returns the stored title, which may be normalized. + +#### SetSessionTitleRequest + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Request parameters for setting the title of a session. + +Only available if the Agent supports the `sessionCapabilities.title` capability. + +The session does not need to be active on the connection. Any session the Agent would +return from `session/list` can be retitled. A session that does not exist gets `-32002`. + +The Agent responds only after it has stored the title. After a successful response, the +Agent SHOULD NOT replace the title with one it generates automatically. + +**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/v1/draft/extensibility) + + +SessionId} required> + The ID of the session to retitle. + + + The new title for the session. + +Required and non-null. Omission and explicit `null` are both invalid. The Agent MAY +normalize the title before storing it, for example by trimming whitespace or +truncating it. The Agent rejects a title that fails its validation, including one +that is empty after normalization, with `-32602`. + + + +#### SetSessionTitleResponse + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Response from setting the title of a session. + +**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/v1/draft/extensibility) + + + + The title the Agent stored. + +This differs from the requested title if the Agent normalized it. Clients SHOULD +display this value rather than the one they sent. + + + ## Client Defines the interface that ACP-compliant clients must implement. @@ -6028,6 +6111,20 @@ Whether the agent supports `systemPrompt` on session lifecycle requests. Optional. Omitted or `null` both mean the agent does not advertise support. Supplying `\{\}` means the agent supports `systemPrompt` in `append` mode. + +SessionTitleCapabilities | null} > + **UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Whether the agent supports `session/set_title`. + +Agents report titles through `session/list` and `session_info_update` without this +capability. It only advertises that Clients can set titles. + +Optional. Omitted or `null` both mean the agent does not advertise support. +Supplying `\{\}` means the agent supports setting session titles. + ## SessionCloseCapabilities @@ -6679,6 +6776,30 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/d +## SessionTitleCapabilities + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Capabilities for Client-set session titles. + +Supplying `\{\}` means the agent supports `session/set_title`. Agents report titles +through `session/list` and `session_info_update` without this capability. + +**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/v1/draft/extensibility) + + + ## SessionUpdate Different types of updates that can be sent during session processing. diff --git a/docs/protocol/v2/draft/error.mdx b/docs/protocol/v2/draft/error.mdx index 8acba108a..4737da917 100644 --- a/docs/protocol/v2/draft/error.mdx +++ b/docs/protocol/v2/draft/error.mdx @@ -60,5 +60,6 @@ Agents **MUST** reject any request other than `initialize` that arrives before i ## Unstable features - `session/fork` of a session that does not exist gets `-32002`, as for [unknown sessions](#unknown-sessions). The source session only has to exist. It doesn't have to be active on the connection. +- `session/set_title` of a session that does not exist gets `-32002`. The session only has to exist. It doesn't have to be active on the connection. A title the Agent rejects gets `-32602`. - A `systemPrompt` the Agent cannot apply gets an error, `-32602` recommended. See [System Prompt](/protocol/v2/draft/session-setup#system-prompt-unstable). - `providers/*` methods called without the [`providers` capability](/protocol/v2/draft/initialization#agent-capabilities) get `-32601`. diff --git a/docs/protocol/v2/draft/initialization.mdx b/docs/protocol/v2/draft/initialization.mdx index a51e0dcba..5bb15b4cc 100644 --- a/docs/protocol/v2/draft/initialization.mdx +++ b/docs/protocol/v2/draft/initialization.mdx @@ -257,6 +257,14 @@ support `session/set_config_option`. empty object means the Agent supports forking sessions. + + **Unstable.** The [`session/set_title`](/rfds/session-set-title) method is + available. Omitted or `null` both mean the Agent does not advertise support. + Supplying an empty object means Clients can set session titles. Agents report + titles through `session/list` and `session_info_update` without this + capability. + + + +### session/set_title + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Sets the title of a session. + +This method is only available if the agent advertises the `session.title` capability. + +The session does not need to be active on the connection. The agent stores the +title and returns the stored title, which may be normalized. + +#### SetSessionTitleRequest + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Request parameters for setting the title of a session. + +Only available if the Agent supports the `session.title` capability. + +The session does not need to be active on the connection. Any session the Agent would +return from `session/list` can be retitled. A session that does not exist gets `-32002`. + +The Agent responds only after it has stored the title. After a successful response, the +Agent SHOULD NOT replace the title with one it generates automatically. + +**Type:** Object + +**Properties:** + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + + +SessionId} required> + The ID of the session to retitle. + + + The new title for the session. + +Required and non-null. Omission and explicit `null` are both invalid. The Agent MAY +normalize the title before storing it, for example by trimming whitespace or +truncating it. The Agent rejects a title that fails its validation, including one +that is empty after normalization, with `-32602`. + + + +#### SetSessionTitleResponse + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Response from setting the title of a session. + +**Type:** Object + +**Properties:** + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + + + + The title the Agent stored. + +This differs from the requested title if the Agent normalized it. Clients SHOULD +display this value rather than the one they sent. + + + ## Client Defines the interface that ACP-compliant clients must implement. @@ -6657,6 +6740,20 @@ Whether the agent supports `systemPrompt` on session lifecycle requests. Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. Supplying `\{\}` means the agent supports `systemPrompt` in `append` mode. + +SessionTitleCapabilities | null} > + **UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Whether the agent supports `session/set_title`. + +Agents report titles through `session/list` and `session_info_update` without this +capability. It only advertises that Clients can set titles. + +Optional. Omitted and `null` are equivalent and mean the agent does not advertise support. +Supplying `\{\}` means the agent supports setting session titles. + ## SessionConfigBoolean @@ -7264,6 +7361,30 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d +## SessionTitleCapabilities + +**UNSTABLE** + +This capability is not part of the spec yet, and may be removed or changed at any point. + +Capabilities for Client-set session titles. + +Supplying `\{\}` means the agent supports `session/set_title`. Agents report titles +through `session/list` and `session_info_update` without this capability. + +**Type:** Object + +**Properties:** + + + The _meta property is reserved by ACP to allow clients and agents to attach additional +metadata to their interactions. Omitted and `null` are equivalent and mean no metadata. +Implementations MUST NOT assign meaning to keys they do not recognize. + +See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility) + + + ## SessionUpdate Different types of updates that can be sent while a session exists. diff --git a/docs/rfds/session-set-title.mdx b/docs/rfds/session-set-title.mdx index 1ff02c032..3f93dfeac 100644 --- a/docs/rfds/session-set-title.mdx +++ b/docs/rfds/session-set-title.mdx @@ -46,7 +46,7 @@ The method is added to both ACP v1 and v2. The request, response, and resulting #### Capability -In v1, an Agent advertises support through `agentCapabilities.sessionCapabilities.setTitle` in the `initialize` response: +In v1, an Agent advertises support through `agentCapabilities.sessionCapabilities.title` in the `initialize` response: ```json { @@ -56,14 +56,14 @@ In v1, an Agent advertises support through `agentCapabilities.sessionCapabilitie "protocolVersion": 1, "agentCapabilities": { "sessionCapabilities": { - "setTitle": {} + "title": {} } } } } ``` -In v2, an Agent advertises support through `capabilities.session.setTitle` in the `initialize` response: +In v2, an Agent advertises support through `capabilities.session.title` in the `initialize` response: ```json { @@ -73,14 +73,14 @@ In v2, an Agent advertises support through `capabilities.session.setTitle` in th "protocolVersion": 2, "capabilities": { "session": { - "setTitle": {} + "title": {} } } } } ``` -In both versions, omitting the field or setting it to `null` means the Agent does not support the method, and `{}` means it does. Clients must not call `session/set_title` unless this capability is present. +In both versions, omitting the field or setting it to `null` means the Agent does not support the method, and `{}` means it does. Clients must not call `session/set_title` unless this capability is present. The capability only covers Client-set titles. Agents report titles through `session/list` and `session_info_update` without it. Later title features, such as an initial title on `session/new`, can add fields to this object. #### Request and response @@ -212,3 +212,4 @@ The main use case is renaming from a session list, where most sessions are not l - 2026-08-19: Initial proposal. - 2026-10-26: Show v1 and v2 capabilities, return the persisted title in the response, allow normalization, allow retitling sessions that are not loaded, make the notification optional, define errors, and add FAQ. +- 2026-10-30: Rename the capability from `setTitle` to `title` so later title features can extend the same object. diff --git a/schema-generator/src/main.rs b/schema-generator/src/main.rs index f580f07c0..904da123d 100644 --- a/schema-generator/src/main.rs +++ b/schema-generator/src/main.rs @@ -2257,6 +2257,7 @@ starting with '$/' it is free to ignore the notification." "session/list" => self.agent.get("ListSessionsRequest").unwrap(), "session/delete" => self.agent.get("DeleteSessionRequest").unwrap(), "session/fork" => self.agent.get("ForkSessionRequest").unwrap(), + "session/set_title" => self.agent.get("SetSessionTitleRequest").unwrap(), "session/resume" => self.agent.get("ResumeSessionRequest").unwrap(), "session/set_mode" => self.agent.get("SetSessionModeRequest").unwrap(), "session/set_config_option" => { diff --git a/schema/v1/meta.unstable.json b/schema/v1/meta.unstable.json index 2b1222e54..913bf5f3a 100644 --- a/schema/v1/meta.unstable.json +++ b/schema/v1/meta.unstable.json @@ -16,6 +16,7 @@ "session_list": "session/list", "session_delete": "session/delete", "session_fork": "session/fork", + "session_set_title": "session/set_title", "session_resume": "session/resume", "session_close": "session/close", "logout": "logout" diff --git a/schema/v1/schema.unstable.json b/schema/v1/schema.unstable.json index 7da67fa8d..30f13b595 100644 --- a/schema/v1/schema.unstable.json +++ b/schema/v1/schema.unstable.json @@ -2338,6 +2338,15 @@ } ] }, + { + "title": "SetSessionTitleResponse", + "description": "Successful result returned for a `session/set_title` request.", + "allOf": [ + { + "$ref": "#/$defs/SetSessionTitleResponse" + } + ] + }, { "title": "ResumeSessionResponse", "description": "Successful result returned for a `session/resume` request.", @@ -2702,6 +2711,18 @@ ], "x-deserialize-default-on-error": true }, + "title": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhether the agent supports `session/set_title`.\n\nAgents report titles through `session/list` and `session_info_update` without this\ncapability. It only advertises that Clients can set titles.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports setting session titles.", + "anyOf": [ + { + "$ref": "#/$defs/SessionTitleCapabilities" + }, + { + "type": "null" + } + ], + "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": [ @@ -2842,6 +2863,18 @@ } } }, + "SessionTitleCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapabilities for Client-set session titles.\n\nSupplying `{}` means the agent supports `session/set_title`. Agents report titles\nthrough `session/list` and `session_info_update` without this capability.", + "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/v1/draft/extensibility)", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + } + }, "SessionResumeCapabilities": { "description": "Capabilities for the `session/resume` method.\n\nSupplying `{}` means the agent supports resuming sessions.", "type": "object", @@ -3751,6 +3784,25 @@ "x-side": "agent", "x-method": "session/fork" }, + "SetSessionTitleResponse": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse from setting the title of a session.", + "type": "object", + "properties": { + "title": { + "description": "The title the Agent stored.\n\nThis differs from the requested title if the Agent normalized it. Clients SHOULD\ndisplay this value rather than the one they sent.", + "type": "string" + }, + "_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/v1/draft/extensibility)", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": ["title"], + "x-side": "agent", + "x-method": "session/set_title" + }, "ResumeSessionResponse": { "description": "Response from resuming an existing session.", "type": "object", @@ -5928,6 +5980,15 @@ } ] }, + { + "title": "SetSessionTitleRequest", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSets the title of a session.\n\nThis method is only available if the agent advertises the `sessionCapabilities.title` capability.\n\nThe session does not need to be active on the connection. The agent stores the\ntitle and returns the stored title, which may be normalized.", + "allOf": [ + { + "$ref": "#/$defs/SetSessionTitleRequest" + } + ] + }, { "title": "ResumeSessionRequest", "description": "Resumes an existing session without returning previous messages.\n\nThis method is only available if the agent advertises the `sessionCapabilities.resume` capability.\n\nThe agent should resume the session context, allowing the conversation to continue\nwithout replaying the message history (unlike `session/load`).", @@ -6922,6 +6983,33 @@ "x-side": "agent", "x-method": "session/fork" }, + "SetSessionTitleRequest": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for setting the title of a session.\n\nOnly available if the Agent supports the `sessionCapabilities.title` capability.\n\nThe session does not need to be active on the connection. Any session the Agent would\nreturn from `session/list` can be retitled. A session that does not exist gets `-32002`.\n\nThe Agent responds only after it has stored the title. After a successful response, the\nAgent SHOULD NOT replace the title with one it generates automatically.", + "type": "object", + "properties": { + "sessionId": { + "description": "The ID of the session to retitle.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "title": { + "description": "The new title for the session.\n\nRequired and non-null. Omission and explicit `null` are both invalid. The Agent MAY\nnormalize the title before storing it, for example by trimming whitespace or\ntruncating it. The Agent rejects a title that fails its validation, including one\nthat is empty after normalization, with `-32602`.", + "type": "string" + }, + "_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/v1/draft/extensibility)", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": ["sessionId", "title"], + "x-side": "agent", + "x-method": "session/set_title" + }, "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 `sessionCapabilities.resume` capability.", "type": "object", diff --git a/schema/v2/meta.unstable.json b/schema/v2/meta.unstable.json index 1b4813ad5..c7da96270 100644 --- a/schema/v2/meta.unstable.json +++ b/schema/v2/meta.unstable.json @@ -14,6 +14,7 @@ "session_list": "session/list", "session_delete": "session/delete", "session_fork": "session/fork", + "session_set_title": "session/set_title", "session_resume": "session/resume", "session_close": "session/close", "auth_logout": "auth/logout" diff --git a/schema/v2/schema.unstable.json b/schema/v2/schema.unstable.json index 959c199bd..9a9c562aa 100644 --- a/schema/v2/schema.unstable.json +++ b/schema/v2/schema.unstable.json @@ -2722,6 +2722,15 @@ } ] }, + { + "title": "SetSessionTitleResponse", + "description": "Successful result returned for a `session/set_title` request.", + "allOf": [ + { + "$ref": "#/$defs/SetSessionTitleResponse" + } + ] + }, { "title": "ResumeSessionResponse", "description": "Successful result returned for a `session/resume` request.", @@ -3017,6 +3026,18 @@ ], "x-deserialize-default-on-error": true }, + "title": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhether the agent supports `session/set_title`.\n\nAgents report titles through `session/list` and `session_info_update` without this\ncapability. It only advertises that Clients can set titles.\n\nOptional. Omitted and `null` are equivalent and mean the agent does not advertise support.\nSupplying `{}` means the agent supports setting session titles.", + "anyOf": [ + { + "$ref": "#/$defs/SessionTitleCapabilities" + }, + { + "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. Omitted and `null` are equivalent and mean no metadata.\nImplementations MUST NOT assign meaning to keys they do not recognize.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", "type": ["object", "null"], @@ -3289,6 +3310,18 @@ } } }, + "SessionTitleCapabilities": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapabilities for Client-set session titles.\n\nSupplying `{}` means the agent supports `session/set_title`. Agents report titles\nthrough `session/list` and `session_info_update` without this capability.", + "type": "object", + "properties": { + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted and `null` are equivalent and mean no metadata.\nImplementations MUST NOT assign meaning to keys they do not recognize.\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 extension capabilities supported by the agent.\n\nThis object does not advertise support for `auth/login` or `auth/logout`.\nThose methods are advertised by a non-empty `authMethods` list in the\n`initialize` response.", "type": "object", @@ -4302,6 +4335,25 @@ "x-side": "agent", "x-method": "session/fork" }, + "SetSessionTitleResponse": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse from setting the title of a session.", + "type": "object", + "properties": { + "title": { + "description": "The title the Agent stored.\n\nThis differs from the requested title if the Agent normalized it. Clients SHOULD\ndisplay this value rather than the one they sent.", + "type": "string" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted and `null` are equivalent and mean no metadata.\nImplementations MUST NOT assign meaning to keys they do not recognize.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": ["title"], + "x-side": "agent", + "x-method": "session/set_title" + }, "ResumeSessionResponse": { "description": "Response from resuming an existing session.\n\nThe agent MUST send a current `state_update` after any requested history\nreplay and before this response, even without replay. The update reports\nforeground state after resuming. The response alone does not imply `idle`.\n\nSee protocol docs: [Current-State Synchronization](https://agentclientprotocol.com/protocol/v2/draft/session-setup#current-state-synchronization)", "type": "object", @@ -6981,6 +7033,15 @@ } ] }, + { + "title": "SetSessionTitleRequest", + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nSets the title of a session.\n\nThis method is only available if the agent advertises the `session.title` capability.\n\nThe session does not need to be active on the connection. The agent stores the\ntitle and returns the stored title, which may be normalized.", + "allOf": [ + { + "$ref": "#/$defs/SetSessionTitleRequest" + } + ] + }, { "title": "ResumeSessionRequest", "description": "Resumes an existing session.\n\nThe agent should resume the session context, allowing the conversation\nto continue. If `replayFrom` is set, the agent should replay\nretained conversation history before responding.", @@ -7759,6 +7820,33 @@ "x-side": "agent", "x-method": "session/fork" }, + "SetSessionTitleRequest": { + "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for setting the title of a session.\n\nOnly available if the Agent supports the `session.title` capability.\n\nThe session does not need to be active on the connection. Any session the Agent would\nreturn from `session/list` can be retitled. A session that does not exist gets `-32002`.\n\nThe Agent responds only after it has stored the title. After a successful response, the\nAgent SHOULD NOT replace the title with one it generates automatically.", + "type": "object", + "properties": { + "sessionId": { + "description": "The ID of the session to retitle.", + "allOf": [ + { + "$ref": "#/$defs/SessionId" + } + ] + }, + "title": { + "description": "The new title for the session.\n\nRequired and non-null. Omission and explicit `null` are both invalid. The Agent MAY\nnormalize the title before storing it, for example by trimming whitespace or\ntruncating it. The Agent rejects a title that fails its validation, including one\nthat is empty after normalization, with `-32602`.", + "type": "string" + }, + "_meta": { + "description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Omitted and `null` are equivalent and mean no metadata.\nImplementations MUST NOT assign meaning to keys they do not recognize.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)", + "type": ["object", "null"], + "x-deserialize-default-on-error": true, + "additionalProperties": true + } + }, + "required": ["sessionId", "title"], + "x-side": "agent", + "x-method": "session/set_title" + }, "ResumeSessionRequest": { "description": "Request parameters for resuming an existing session.\n\nResumes an existing session and optionally replays retained conversation\nhistory according to `replayFrom`.", "type": "object",