feat(rust): Expose v1 schema types only under v1 module (#1457)

* fix: Cleanup rust crate exports and trait derives

* feat: Expose v1 schema types only under v1 module

Prepares the way for multiple versions exported from the same crate.

Accepting the breaking change pre-1.0

Author: benbrandt

agent-client-protocol-schema/src/lib.rs

@@ -19,34 +19,34 @@
 //!
 //! ## What's in this crate
 //!
-//! - Wire-format types for every ACP method: request, response, and
-//!   notification structs grouped by which side handles them.
-//! - JSON-RPC envelope and routing types: [`JsonRpcMessage`],
-//!   [`rpc::JsonRpcBatch`], [`Request`], [`Response`], [`Notification`],
-//!   [`RequestId`], [`Error`].
-//! - Aggregated routing enums: [`AgentRequest`], [`AgentResponse`],
-//!   [`AgentNotification`], and the matching client-side trio used by SDK
+//! - Versioned wire-format types for every ACP method: request, response, and
+//!   notification structs grouped by which side handles them, currently under
+//!   the [`v1`] module.
+//! - JSON-RPC envelope and routing types: [`v1::JsonRpcMessage`],
+//!   [`rpc::JsonRpcBatch`], [`v1::Request`], [`v1::Response`],
+//!   [`v1::Notification`], [`v1::RequestId`], [`v1::Error`].
+//! - Aggregated routing enums: [`v1::AgentRequest`], [`v1::AgentResponse`],
+//!   [`v1::AgentNotification`], and the matching client-side trio used by SDK
 //!   crates to dispatch incoming JSON-RPC messages.
 //!
 //! ## Versioning
 //!
-//! The default surface re-exports the v1 (current stable) protocol types
-//! directly at the crate root, so most consumers can write
-//! `agent_client_protocol_schema::SessionId` (and so on) without thinking
-//! about versions.
+//! Stable protocol types are exposed through explicit version modules. For
+//! example, use `agent_client_protocol_schema::v1::SessionId` for ACP protocol
+//! version 1 types.
 //!
 //! For the complete protocol specification and documentation, visit
 //! <https://agentclientprotocol.com>.
 
 pub mod rpc;
 mod serde_util;
-mod v1;
+pub mod v1;
 #[cfg(feature = "unstable_protocol_v2")]
 pub mod v2;
 mod version;
 
-pub use serde_util::*;
-pub use v1::*;
+pub(crate) use serde_util::SkipListener;
+pub use serde_util::{IntoMaybeUndefined, IntoOption, MaybeUndefined};
 pub use version::*;
 
 #[cfg(test)]

agent-client-protocol-schema/src/rpc.rs

@@ -50,7 +50,7 @@ pub enum RequestId {
 }
 
 /// A JSON-RPC request object.
-#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)]
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
 #[allow(
     clippy::exhaustive_structs,
     reason = "This comes from the JSON-RPC specification itself"
@@ -67,7 +67,7 @@ pub struct Request<Params> {
 }
 
 /// A JSON-RPC response object.
-#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)]
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
 #[allow(
     clippy::exhaustive_enums,
     reason = "This comes from the JSON-RPC specification itself"
@@ -109,7 +109,7 @@ impl<R, E> Response<R, E> {
 }
 
 /// A JSON-RPC notification object.
-#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema)]
+#[derive(Serialize, Deserialize, Clone, Debug, PartialEq, Eq, JsonSchema)]
 #[allow(
     clippy::exhaustive_structs,
     reason = "This comes from the JSON-RPC specification itself"
@@ -123,7 +123,7 @@ pub struct Notification<Params> {
     pub params: Option<Params>,
 }
 
-#[derive(Debug, Serialize, Deserialize, JsonSchema)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
 #[schemars(inline)]
 enum JsonRpcVersion {
     #[serde(rename = "2.0")]
@@ -134,7 +134,7 @@ enum JsonRpcVersion {
 /// [required by JSON-RPC 2.0 Specification][1].
 ///
 /// [1]: https://www.jsonrpc.org/specification#compatibility
-#[derive(Debug, Serialize, Deserialize, JsonSchema)]
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
 #[schemars(inline)]
 pub struct JsonRpcMessage<M> {
     jsonrpc: JsonRpcVersion,
@@ -174,7 +174,7 @@ pub struct EmptyJsonRpcBatch;
 impl std::error::Error for EmptyJsonRpcBatch {}
 
 /// A non-empty JSON-RPC 2.0 batch message.
-#[derive(Debug, Serialize, JsonSchema)]
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, JsonSchema)]
 #[schemars(inline)]
 #[serde(transparent)]
 #[allow(
@@ -238,7 +238,7 @@ where
 mod tests {
     use super::*;
 
-    use crate::{
+    use crate::v1::{
         AgentNotification, CancelNotification, ClientNotification, ContentBlock, ContentChunk,
         SessionId, SessionNotification, SessionUpdate, TextContent,
     };

agent-client-protocol-schema/src/serde_util.rs

@@ -39,7 +39,7 @@ use serde_with::{DeserializeAs, de::DeserializeAsWrap};
 #[cfg(feature = "tracing")]
 #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash)]
 #[non_exhaustive]
-pub struct SkipListener;
+pub(crate) struct SkipListener;
 
 #[cfg(feature = "tracing")]
 impl serde_with::InspectError for SkipListener {
@@ -55,7 +55,7 @@ impl serde_with::InspectError for SkipListener {
 /// disabled. Resolves to `()`, which `serde_with` already ships with a no-op
 /// `InspectError` implementation.
 #[cfg(not(feature = "tracing"))]
-pub type SkipListener = ();
+pub(crate) type SkipListener = ();
 
 #[cfg(test)]
 mod skip_listener_tests {

agent-client-protocol-schema/src/v1/agent.rs

@@ -13,9 +13,10 @@ use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use serde_with::{DefaultOnError, VecSkipError, serde_as, skip_serializing_none};
 
-use crate::{
-    ClientCapabilities, ContentBlock, ExtNotification, ExtRequest, ExtResponse, IntoOption, Meta,
-    ProtocolVersion, SessionId, SkipListener,
+use crate::{IntoOption, ProtocolVersion, SkipListener};
+
+use super::{
+    ClientCapabilities, ContentBlock, ExtNotification, ExtRequest, ExtResponse, Meta, SessionId,
 };
 
 #[cfg(feature = "unstable_mcp_over_acp")]
@@ -24,15 +25,15 @@ use super::mcp::{
 };
 
 #[cfg(feature = "unstable_nes")]
-use crate::{
+use super::{
     AcceptNesNotification, CloseNesRequest, CloseNesResponse, DidChangeDocumentNotification,
     DidCloseDocumentNotification, DidFocusDocumentNotification, DidOpenDocumentNotification,
     DidSaveDocumentNotification, NesCapabilities, PositionEncodingKind, RejectNesNotification,
     StartNesRequest, StartNesResponse, SuggestNesRequest, SuggestNesResponse,
 };
 
 #[cfg(feature = "unstable_nes")]
-use crate::{
+use super::{
     DOCUMENT_DID_CHANGE_METHOD_NAME, DOCUMENT_DID_CLOSE_METHOD_NAME,
     DOCUMENT_DID_FOCUS_METHOD_NAME, DOCUMENT_DID_OPEN_METHOD_NAME, DOCUMENT_DID_SAVE_METHOD_NAME,
     NES_ACCEPT_METHOD_NAME, NES_CLOSE_METHOD_NAME, NES_REJECT_METHOD_NAME, NES_START_METHOD_NAME,

agent-client-protocol-schema/src/v1/client.rs

@@ -11,17 +11,18 @@ use serde::{Deserialize, Serialize};
 use serde_with::{DefaultOnError, VecSkipError, serde_as, skip_serializing_none};
 
 #[cfg(feature = "unstable_elicitation")]
-use crate::{
+use super::{
     CompleteElicitationNotification, CreateElicitationRequest, CreateElicitationResponse,
     ElicitationCapabilities,
 };
-use crate::{
-    ContentBlock, EnvVariable, ExtNotification, ExtRequest, ExtResponse, IntoMaybeUndefined,
-    IntoOption, MaybeUndefined, Meta, Plan, SessionConfigOption, SessionId, SessionModeId,
-    SkipListener, ToolCall, ToolCallUpdate,
+use crate::{IntoMaybeUndefined, IntoOption, MaybeUndefined, SkipListener};
+
+use super::{
+    ContentBlock, EnvVariable, ExtNotification, ExtRequest, ExtResponse, Meta, Plan,
+    SessionConfigOption, SessionId, SessionModeId, ToolCall, ToolCallUpdate,
 };
 #[cfg(feature = "unstable_plan_operations")]
-use crate::{PlanCapabilities, PlanRemoved, PlanUpdate};
+use super::{PlanCapabilities, PlanRemoved, PlanUpdate};
 
 #[cfg(feature = "unstable_mcp_over_acp")]
 use super::mcp::{
@@ -31,7 +32,7 @@ use super::mcp::{
 };
 
 #[cfg(feature = "unstable_nes")]
-use crate::{ClientNesCapabilities, PositionEncodingKind};
+use super::{ClientNesCapabilities, PositionEncodingKind};
 
 // Session updates
 
@@ -2281,7 +2282,7 @@ mod tests {
 
         assert_eq!(
             serde_json::to_value(SessionUpdate::AgentMessageChunk(ContentChunk::new(
-                ContentBlock::Text(crate::TextContent::new("Hello"))
+                ContentBlock::Text(crate::v1::TextContent::new("Hello"))
             )))
             .unwrap(),
             json!({
@@ -2295,7 +2296,7 @@ mod tests {
 
         assert_eq!(
             serde_json::to_value(SessionUpdate::AgentMessageChunk(
-                ContentChunk::new(ContentBlock::Text(crate::TextContent::new("Hello")))
+                ContentChunk::new(ContentBlock::Text(crate::v1::TextContent::new("Hello")))
                     .message_id("msg_agent_c42b9")
             ))
             .unwrap(),
@@ -2388,15 +2389,16 @@ mod tests {
     fn test_plan_operations_serialization() {
         use serde_json::json;
 
-        let plan_update =
-            SessionUpdate::PlanUpdate(PlanUpdate::new(crate::PlanUpdateContent::items(
-                "plan-1",
-                vec![crate::PlanEntry::new(
-                    "Step 1",
-                    crate::PlanEntryPriority::High,
-                    crate::PlanEntryStatus::Pending,
-                )],
-            )));
+        use crate::v1::{PlanEntry, PlanEntryPriority, PlanEntryStatus, PlanUpdateContent};
+
+        let plan_update = SessionUpdate::PlanUpdate(PlanUpdate::new(PlanUpdateContent::items(
+            "plan-1",
+            vec![PlanEntry::new(
+                "Step 1",
+                PlanEntryPriority::High,
+                PlanEntryStatus::Pending,
+            )],
+        )));
 
         assert_eq!(
             serde_json::to_value(plan_update).unwrap(),

agent-client-protocol-schema/src/v1/content.rs

@@ -13,7 +13,9 @@ use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use serde_with::{DefaultOnError, VecSkipError, serde_as, skip_serializing_none};
 
-use crate::{IntoOption, Meta, SkipListener};
+use crate::{IntoOption, SkipListener};
+
+use super::Meta;
 
 /// Content blocks represent displayable information in the Agent Client Protocol.
 ///

agent-client-protocol-schema/src/v1/elicitation.rs

@@ -12,9 +12,11 @@ use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use serde_with::{DefaultOnError, serde_as, skip_serializing_none};
 
-use crate::{
-    ELICITATION_COMPLETE_NOTIFICATION, ELICITATION_CREATE_METHOD_NAME, IntoOption, Meta, RequestId,
-    SessionId, ToolCallId,
+use crate::IntoOption;
+
+use super::{
+    ELICITATION_COMPLETE_NOTIFICATION, ELICITATION_CREATE_METHOD_NAME, Meta, RequestId, SessionId,
+    ToolCallId,
 };
 
 /// **UNSTABLE**
@@ -1729,7 +1731,7 @@ mod tests {
     /// concrete `CreateElicitationResponse` type.
     #[test]
     fn client_response_serialization_accept() {
-        use crate::ClientResponse;
+        use crate::v1::ClientResponse;
 
         let resp = ClientResponse::CreateElicitationResponse(CreateElicitationResponse::new(
             ElicitationAction::Accept(ElicitationAcceptAction::new().content(BTreeMap::from([(
@@ -1748,7 +1750,7 @@ mod tests {
 
     #[test]
     fn client_response_serialization_decline() {
-        use crate::ClientResponse;
+        use crate::v1::ClientResponse;
 
         let resp = ClientResponse::CreateElicitationResponse(CreateElicitationResponse::new(
             ElicitationAction::Decline,
@@ -1762,7 +1764,7 @@ mod tests {
 
     #[test]
     fn client_response_serialization_cancel() {
-        use crate::ClientResponse;
+        use crate::v1::ClientResponse;
 
         let resp = ClientResponse::CreateElicitationResponse(CreateElicitationResponse::new(
             ElicitationAction::Cancel,

agent-client-protocol-schema/src/v1/mcp.rs

@@ -8,7 +8,9 @@ use serde::{Deserialize, Serialize};
 use serde_json::value::RawValue;
 use serde_with::skip_serializing_none;
 
-use crate::{IntoOption, McpServerAcpId, Meta};
+use crate::IntoOption;
+
+use super::{McpServerAcpId, Meta};
 
 /// **UNSTABLE**
 ///

agent-client-protocol-schema/src/v1/mod.rs

@@ -16,7 +16,7 @@ mod plan;
 mod protocol_level;
 mod tool_call;
 
-pub use crate::rpc::{JsonRpcMessage, Notification, Request, RequestId};
+pub use crate::rpc::{JsonRpcBatch, JsonRpcMessage, Notification, Request, RequestId};
 pub use agent::*;
 pub use client::*;
 pub use content::*;

agent-client-protocol-schema/src/v1/nes.rs

@@ -8,7 +8,9 @@ use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use serde_with::{DefaultOnError, VecSkipError, serde_as, skip_serializing_none};
 
-use crate::{IntoOption, Meta, SessionId, SkipListener};
+use crate::{IntoOption, SkipListener};
+
+use super::{Meta, SessionId};
 
 // Method name constants