Skip to content

docs(schema): Clean up generated documentation and make wording more consistent #1568

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
benbrandt merged 3 commits into from
Jul 1, 2026
Merged

docs(schema): Clean up generated documentation and make wording more consistent #1568

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3831b4d
docs(schema): Clarify absolute path requirements
benbrandt Jul 1, 2026
195616f
docs(schema): clarify nullable capabilities semantics
benbrandt Jul 1, 2026
73a2c4a
Clean up inconsistent drafts
benbrandt Jul 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 51 additions & 14 deletions agent-client-protocol-schema/src/v1/agent.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -460,7 +460,8 @@ impl LogoutResponse {
pub struct AgentAuthCapabilities {
/// Whether the agent supports the logout method.
///
/// By supplying `{}` it means that the agent supports the logout method.
/// Optional. Omitted or `null` both mean the agent does not advertise support.
/// Supplying `{}` means the agent supports the logout method.
#[serde_as(deserialize_as = "DefaultOnError")]
#[schemars(extend("x-deserialize-default-on-error" = true))]
#[serde(default)]
Expand Down Expand Up @@ -505,7 +506,7 @@ impl AgentAuthCapabilities {

/// Logout capabilities supported by the agent.
///
/// By supplying `{}` it means that the agent supports the logout method.
/// Supplying `{}` means the agent supports the logout method.
#[serde_as]
#[skip_serializing_none]
#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
Expand Down Expand Up @@ -1172,7 +1173,7 @@ pub struct LoadSessionRequest {
#[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_, SkipListener>>")]
#[schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true))]
pub mcp_servers: Vec<McpServer>,
/// The working directory for this session.
/// The working directory for this session. Must be an absolute path.
pub cwd: PathBuf,
/// Additional workspace roots to activate for this session. Each path must be absolute.
///
Expand Down Expand Up @@ -1329,7 +1330,7 @@ impl LoadSessionResponse {
pub struct ForkSessionRequest {
/// The ID of the session to fork.
pub session_id: SessionId,
/// The working directory for this session.
/// The working directory for this session. Must be an absolute path.
pub cwd: PathBuf,
/// Additional workspace roots to activate for this session. Each path must be absolute.
///
Expand Down Expand Up @@ -1497,7 +1498,7 @@ impl ForkSessionResponse {
pub struct ResumeSessionRequest {
/// The ID of the session to resume.
pub session_id: SessionId,
/// The working directory for this session.
/// The working directory for this session. Must be an absolute path.
pub cwd: PathBuf,
/// Additional workspace roots to activate for this session. Each path must be absolute.
///
Expand Down Expand Up @@ -3094,7 +3095,7 @@ impl McpServerAcp {
pub struct McpServerStdio {
/// Human-readable name identifying this MCP server.
pub name: String,
/// Path to the MCP server executable.
/// Absolute path to the MCP server executable.
pub command: PathBuf,
/// Command-line arguments to pass to the MCP server.
#[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_, SkipListener>>")]
Expand Down Expand Up @@ -4041,7 +4042,8 @@ pub struct AgentCapabilities {
///
/// Provider configuration capabilities supported by the agent.
///
/// By supplying `{}` it means that the agent supports provider configuration methods.
/// Optional. Omitted or `null` both mean the agent does not advertise support.
/// Supplying `{}` means the agent supports provider configuration methods.
#[cfg(feature = "unstable_llm_providers")]
#[serde_as(deserialize_as = "DefaultOnError")]
#[schemars(extend("x-deserialize-default-on-error" = true))]
Expand All @@ -4052,6 +4054,9 @@ pub struct AgentCapabilities {
/// This capability is not part of the spec yet, and may be removed or changed at any point.
///
/// NES (Next Edit Suggestions) capabilities supported by the agent.
///
/// Optional. Omitted or `null` both mean the agent does not advertise support
/// for NES methods.
#[cfg(feature = "unstable_nes")]
#[serde_as(deserialize_as = "DefaultOnError")]
#[schemars(extend("x-deserialize-default-on-error" = true))]
Expand Down Expand Up @@ -4176,7 +4181,7 @@ impl AgentCapabilities {
///
/// Provider configuration capabilities supported by the agent.
///
/// By supplying `{}` it means that the agent supports provider configuration methods.
/// Supplying `{}` means the agent supports provider configuration methods.
#[cfg(feature = "unstable_llm_providers")]
#[serde_as]
#[skip_serializing_none]
Expand Down Expand Up @@ -4231,6 +4236,9 @@ impl ProvidersCapabilities {
#[non_exhaustive]
pub struct SessionCapabilities {
/// 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)]
Expand All @@ -4245,6 +4253,10 @@ pub struct SessionCapabilities {
pub delete: Option<SessionDeleteCapabilities>,
/// Whether the agent supports `additionalDirectories` on supported session lifecycle requests.
///
/// 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.
Expand All @@ -4257,17 +4269,26 @@ pub struct SessionCapabilities {
/// This capability is not part of the spec yet, and may be removed or changed at any point.
///
/// 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.
#[cfg(feature = "unstable_session_fork")]
#[serde_as(deserialize_as = "DefaultOnError")]
#[schemars(extend("x-deserialize-default-on-error" = true))]
#[serde(default)]
pub fork: Option<SessionForkCapabilities>,
/// 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<SessionResumeCapabilities>,
/// 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)]
Expand All @@ -4292,6 +4313,9 @@ impl SessionCapabilities {
}

/// 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<SessionListCapabilities>) -> Self {
self.list = list.into_option();
Expand All @@ -4310,6 +4334,10 @@ impl SessionCapabilities {

/// Whether the agent supports `additionalDirectories` on supported session lifecycle requests.
///
/// 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.
Expand All @@ -4324,20 +4352,29 @@ impl SessionCapabilities {

#[cfg(feature = "unstable_session_fork")]
/// Whether the agent supports `session/fork`.
///
/// Omitted or `null` both mean the agent does not advertise support.
/// Supplying `{}` means the agent supports forking sessions.
#[must_use]
pub fn fork(mut self, fork: impl IntoOption<SessionForkCapabilities>) -> Self {
self.fork = fork.into_option();
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<SessionResumeCapabilities>) -> 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<SessionCloseCapabilities>) -> Self {
self.close = close.into_option();
Expand All @@ -4358,7 +4395,7 @@ impl SessionCapabilities {

/// Capabilities for the `session/list` method.
///
/// By supplying `{}` it means that the agent supports listing of sessions.
/// Supplying `{}` means the agent supports listing sessions.
#[serde_as]
#[skip_serializing_none]
#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
Expand Down Expand Up @@ -4436,8 +4473,8 @@ impl SessionDeleteCapabilities {

/// Capabilities for additional session directories support.
///
/// By supplying `{}` it means that the agent supports the `additionalDirectories`
/// field on supported session lifecycle requests. Agents that also support
/// Supplying `{}` means the agent supports the `additionalDirectories` field 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.
#[serde_as]
Expand Down Expand Up @@ -4482,7 +4519,7 @@ impl SessionAdditionalDirectoriesCapabilities {
///
/// Capabilities for the `session/fork` method.
///
/// By supplying `{}` it means that the agent supports forking of sessions.
/// Supplying `{}` means the agent supports forking sessions.
#[cfg(feature = "unstable_session_fork")]
#[serde_as]
#[skip_serializing_none]
Expand Down Expand Up @@ -4523,7 +4560,7 @@ impl SessionForkCapabilities {

/// Capabilities for the `session/resume` method.
///
/// By supplying `{}` it means that the agent supports resuming of sessions.
/// Supplying `{}` means the agent supports resuming sessions.
#[serde_as]
#[skip_serializing_none]
#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
Expand Down Expand Up @@ -4562,7 +4599,7 @@ impl SessionResumeCapabilities {

/// Capabilities for the `session/close` method.
///
/// By supplying `{}` it means that the agent supports closing of sessions.
/// Supplying `{}` means the agent supports closing sessions.
#[serde_as]
#[skip_serializing_none]
#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
Expand Down
25 changes: 17 additions & 8 deletions agent-client-protocol-schema/src/v1/client.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1148,7 +1148,7 @@ pub struct CreateTerminalRequest {
#[schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true))]
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub env: Vec<EnvVariable>,
/// Working directory for the command (absolute path).
/// Working directory for the command. Must be an absolute path.
#[serde_as(deserialize_as = "DefaultOnError")]
#[schemars(extend("x-deserialize-default-on-error" = true))]
#[serde(default)]
Expand Down Expand Up @@ -1206,7 +1206,7 @@ impl CreateTerminalRequest {
self
}

/// Working directory for the command (absolute path).
/// Working directory for the command. Must be an absolute path.
#[must_use]
pub fn cwd(mut self, cwd: impl IntoOption<PathBuf>) -> Self {
self.cwd = cwd.into_option();
Expand Down Expand Up @@ -1746,6 +1746,9 @@ pub struct ClientCapabilities {
/// This capability is not part of the spec yet, and may be removed or changed at any point.
///
/// Session-related capabilities supported by the client.
///
/// Optional. Omitted or `null` both mean the client does not advertise any
/// session-related extensions.
#[cfg(feature = "unstable_boolean_config")]
#[serde_as(deserialize_as = "DefaultOnError")]
#[schemars(extend("x-deserialize-default-on-error" = true))]
Expand All @@ -1757,7 +1760,7 @@ pub struct ClientCapabilities {
///
/// Whether the client supports `plan_update` and `plan_removed` session updates.
///
/// Optional. Omitted means the client does not advertise support.
/// Optional. Omitted or `null` both mean the client does not advertise support.
/// Supplying `{}` means the client can receive both update types.
#[cfg(feature = "unstable_plan_operations")]
#[serde_as(deserialize_as = "DefaultOnError")]
Expand All @@ -1782,6 +1785,9 @@ pub struct ClientCapabilities {
///
/// Elicitation capabilities supported by the client.
/// Determines which elicitation modes the agent may use.
///
/// Optional. Omitted or `null` both mean the client does not advertise
/// elicitation support.
#[cfg(feature = "unstable_elicitation")]
#[serde_as(deserialize_as = "DefaultOnError")]
#[schemars(extend("x-deserialize-default-on-error" = true))]
Expand All @@ -1792,6 +1798,9 @@ pub struct ClientCapabilities {
/// This capability is not part of the spec yet, and may be removed or changed at any point.
///
/// NES (Next Edit Suggestions) capabilities supported by the client.
///
/// Optional. Omitted or `null` both mean the client does not advertise any
/// NES suggestion-kind extensions.
#[cfg(feature = "unstable_nes")]
#[serde_as(deserialize_as = "DefaultOnError")]
#[schemars(extend("x-deserialize-default-on-error" = true))]
Expand Down Expand Up @@ -1860,7 +1869,7 @@ impl ClientCapabilities {
///
/// Whether the client supports `plan_update` and `plan_removed` session updates.
///
/// Omitted means the client does not advertise support.
/// Omitted or `null` both mean the client does not advertise support.
/// Supplying `{}` means the client can receive both update types.
#[cfg(feature = "unstable_plan_operations")]
#[must_use]
Expand Down Expand Up @@ -1942,7 +1951,7 @@ impl ClientCapabilities {
pub struct ClientSessionCapabilities {
/// Config option capabilities supported by the client.
///
/// Omitted or `null` means the client does not advertise support for any
/// Omitted or `null` both mean the client does not advertise support for any
/// config option extensions.
#[serde_as(deserialize_as = "DefaultOnError")]
#[schemars(extend("x-deserialize-default-on-error" = true))]
Expand Down Expand Up @@ -1970,7 +1979,7 @@ impl ClientSessionCapabilities {

/// Config option capabilities supported by the client.
///
/// Omitted or `null` means the client does not advertise support for any
/// Omitted or `null` both mean the client does not advertise support for any
/// config option extensions.
#[must_use]
pub fn config_options(
Expand Down Expand Up @@ -2007,7 +2016,7 @@ impl ClientSessionCapabilities {
pub struct SessionConfigOptionsCapabilities {
/// Whether the client supports boolean session configuration options.
///
/// Omitted or `null` means the client does not advertise support.
/// Optional. Omitted or `null` both mean the client does not advertise support.
/// Supplying `{}` means agents may include `type: "boolean"` entries in
/// `configOptions`, and the client may send `session/set_config_option`
/// requests with `type: "boolean"` and a boolean `value`.
Expand Down Expand Up @@ -2037,7 +2046,7 @@ impl SessionConfigOptionsCapabilities {

/// Whether the client supports boolean session configuration options.
///
/// Omitted or `null` means the client does not advertise support.
/// Omitted or `null` both mean the client does not advertise support.
/// Supplying `{}` means agents may include `type: "boolean"` entries in
/// `configOptions`, and the client may send `session/set_config_option`
/// requests with `type: "boolean"` and a boolean `value`.
Expand Down
16 changes: 16 additions & 0 deletions agent-client-protocol-schema/src/v1/elicitation.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1049,11 +1049,17 @@ impl ElicitationSchema {
#[non_exhaustive]
pub struct ElicitationCapabilities {
/// Whether the client supports form-based elicitation.
///
/// Optional. Omitted or `null` both mean the client does not advertise support.
/// Supplying `{}` means the client supports form-based elicitation.
#[serde_as(deserialize_as = "DefaultOnError")]
#[schemars(extend("x-deserialize-default-on-error" = true))]
#[serde(default)]
pub form: Option<ElicitationFormCapabilities>,
/// Whether the client supports URL-based elicitation.
///
/// Optional. Omitted or `null` both mean the client does not advertise support.
/// Supplying `{}` means the client supports URL-based elicitation.
#[serde_as(deserialize_as = "DefaultOnError")]
#[schemars(extend("x-deserialize-default-on-error" = true))]
#[serde(default)]
Expand All @@ -1078,13 +1084,19 @@ impl ElicitationCapabilities {
}

/// Whether the client supports form-based elicitation.
///
/// Omitted or `null` both mean the client does not advertise support.
/// Supplying `{}` means the client supports form-based elicitation.
#[must_use]
pub fn form(mut self, form: impl IntoOption<ElicitationFormCapabilities>) -> Self {
self.form = form.into_option();
self
}

/// Whether the client supports URL-based elicitation.
///
/// Omitted or `null` both mean the client does not advertise support.
/// Supplying `{}` means the client supports URL-based elicitation.
#[must_use]
pub fn url(mut self, url: impl IntoOption<ElicitationUrlCapabilities>) -> Self {
self.url = url.into_option();
Expand All @@ -1108,6 +1120,8 @@ impl ElicitationCapabilities {
/// This capability is not part of the spec yet, and may be removed or changed at any point.
///
/// Form-based elicitation capabilities.
///
/// Supplying `{}` means the client supports form-based elicitation.
#[serde_as]
#[skip_serializing_none]
#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
Expand Down Expand Up @@ -1150,6 +1164,8 @@ impl ElicitationFormCapabilities {
/// This capability is not part of the spec yet, and may be removed or changed at any point.
///
/// URL-based elicitation capabilities.
///
/// Supplying `{}` means the client supports URL-based elicitation.
#[serde_as]
#[skip_serializing_none]
#[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
Expand Down
Loading