Add optional tracing for skipped list entries

Introduce a `tracing` feature that logs `VecSkipError` drops via a
shared `SkipListener` inspector, while remaining a zero-cost no-op
when the feature is disabled.

Also add tests covering inspector callbacks for malformed entries.

Author: benbrandt

Cargo.lock

@@ -45,6 +45,11 @@ unstable_session_usage = []
 unstable_message_id = []
 unstable_boolean_config = []
 
+# Emit `tracing::warn!` events when `VecSkipError` drops a malformed list
+# entry during deserialization. When disabled (the default), the inspector
+# hook compiles down to serde_with's built-in no-op and has zero runtime cost.
+tracing = ["dep:tracing"]
+
 [[bin]]
 name = "generate"
 path = "src/bin/generate.rs"
@@ -57,6 +62,7 @@ serde = { version = "1", features = ["derive", "rc"] }
 serde_json = { version = "1", features = ["raw_value"] }
 serde_with = { version = "3.18.0", features = ["json", "schemars_1"] }
 strum = { version = "0.28", features = ["derive"] }
+tracing = { version = "0.1", default-features = false, optional = true }
 
 [lints.rust]
 future_incompatible = { level = "warn", priority = -1 }

Cargo.toml

@@ -17,7 +17,7 @@ use serde_with::{DefaultOnError, VecSkipError, serde_as, skip_serializing_none};
 use crate::RequiredNullable;
 use crate::{
     ClientCapabilities, ContentBlock, ExtNotification, ExtRequest, ExtResponse, IntoOption, Meta,
-    ProtocolVersion, SessionId,
+    ProtocolVersion, SessionId, SkipListener,
 };
 
 #[cfg(feature = "unstable_nes")]
@@ -128,7 +128,7 @@ pub struct InitializeResponse {
     #[serde(default)]
     pub agent_capabilities: AgentCapabilities,
     /// Authentication methods supported by the agent.
-    #[serde_as(deserialize_as = "VecSkipError<_>")]
+    #[serde_as(deserialize_as = "VecSkipError<_, SkipListener>")]
     #[serde(default)]
     pub auth_methods: Vec<AuthMethod>,
     /// Information about the Agent name and version sent to the Client.
@@ -1024,7 +1024,7 @@ pub struct NewSessionResponse {
     #[serde(default)]
     pub models: Option<SessionModelState>,
     /// Initial session configuration options if supported by the Agent.
-    #[serde_as(deserialize_as = "Option<VecSkipError<_>>")]
+    #[serde_as(deserialize_as = "Option<VecSkipError<_, SkipListener>>")]
     #[serde(default)]
     pub config_options: Option<Vec<SessionConfigOption>>,
     /// The _meta property is reserved by ACP to allow clients and agents to attach additional
@@ -1200,7 +1200,7 @@ pub struct LoadSessionResponse {
     #[serde(default)]
     pub models: Option<SessionModelState>,
     /// Initial session configuration options if supported by the Agent.
-    #[serde_as(deserialize_as = "Option<VecSkipError<_>>")]
+    #[serde_as(deserialize_as = "Option<VecSkipError<_, SkipListener>>")]
     #[serde(default)]
     pub config_options: Option<Vec<SessionConfigOption>>,
     /// The _meta property is reserved by ACP to allow clients and agents to attach additional
@@ -1384,7 +1384,7 @@ pub struct ForkSessionResponse {
     #[serde(default)]
     pub models: Option<SessionModelState>,
     /// Initial session configuration options if supported by the Agent.
-    #[serde_as(deserialize_as = "Option<VecSkipError<_>>")]
+    #[serde_as(deserialize_as = "Option<VecSkipError<_, SkipListener>>")]
     #[serde(default)]
     pub config_options: Option<Vec<SessionConfigOption>>,
     /// The _meta property is reserved by ACP to allow clients and agents to attach additional
@@ -1574,7 +1574,7 @@ pub struct ResumeSessionResponse {
     #[serde(default)]
     pub models: Option<SessionModelState>,
     /// Initial session configuration options if supported by the Agent.
-    #[serde_as(deserialize_as = "Option<VecSkipError<_>>")]
+    #[serde_as(deserialize_as = "Option<VecSkipError<_, SkipListener>>")]
     #[serde(default)]
     pub config_options: Option<Vec<SessionConfigOption>>,
     /// The _meta property is reserved by ACP to allow clients and agents to attach additional
@@ -1817,7 +1817,7 @@ impl ListSessionsRequest {
 #[non_exhaustive]
 pub struct ListSessionsResponse {
     /// Array of session information objects
-    #[serde_as(deserialize_as = "VecSkipError<_>")]
+    #[serde_as(deserialize_as = "VecSkipError<_, SkipListener>")]
     pub sessions: Vec<SessionInfo>,
     /// Opaque cursor token. If present, pass this in the next request's cursor parameter
     /// to fetch the next page. If absent, there are no more results.
@@ -1962,7 +1962,7 @@ pub struct SessionModeState {
     /// The current mode the Agent is in.
     pub current_mode_id: SessionModeId,
     /// The set of modes that the Agent can operate in
-    #[serde_as(deserialize_as = "VecSkipError<_>")]
+    #[serde_as(deserialize_as = "VecSkipError<_, SkipListener>")]
     pub available_modes: Vec<SessionMode>,
     /// 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
@@ -2663,7 +2663,7 @@ impl SetSessionConfigOptionRequest {
 #[non_exhaustive]
 pub struct SetSessionConfigOptionResponse {
     /// The full set of configuration options and their current values.
-    #[serde_as(deserialize_as = "VecSkipError<_>")]
+    #[serde_as(deserialize_as = "VecSkipError<_, SkipListener>")]
     pub config_options: Vec<SessionConfigOption>,
     /// 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
@@ -3255,7 +3255,7 @@ pub struct SessionModelState {
     /// The current model the Agent is in.
     pub current_model_id: ModelId,
     /// The set of models that the Agent can use
-    #[serde_as(deserialize_as = "VecSkipError<_>")]
+    #[serde_as(deserialize_as = "VecSkipError<_, SkipListener>")]
     pub available_models: Vec<ModelInfo>,
     /// 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
@@ -3531,7 +3531,7 @@ pub struct ProviderInfo {
     /// Provider identifier, for example "main" or "openai".
     pub id: String,
     /// Supported protocol types for this provider.
-    #[serde_as(deserialize_as = "VecSkipError<_>")]
+    #[serde_as(deserialize_as = "VecSkipError<_, SkipListener>")]
     pub supported: Vec<LlmProtocol>,
     /// Whether this provider is mandatory and cannot be disabled via `providers/disable`.
     /// If true, clients must not call `providers/disable` for this id.
@@ -3632,7 +3632,7 @@ impl ListProvidersRequest {
 #[non_exhaustive]
 pub struct ListProvidersResponse {
     /// Configurable providers with current routing info suitable for UI display.
-    #[serde_as(deserialize_as = "VecSkipError<_>")]
+    #[serde_as(deserialize_as = "VecSkipError<_, SkipListener>")]
     pub providers: Vec<ProviderInfo>,
     /// 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

src/agent.rs

@@ -17,7 +17,7 @@ use crate::elicitation::{
 };
 use crate::{
     ContentBlock, ExtNotification, ExtRequest, ExtResponse, IntoOption, Meta, Plan,
-    SessionConfigOption, SessionId, SessionModeId, ToolCall, ToolCallUpdate,
+    SessionConfigOption, SessionId, SessionModeId, SkipListener, ToolCall, ToolCallUpdate,
 };
 use crate::{IntoMaybeUndefined, MaybeUndefined};
 
@@ -162,7 +162,7 @@ impl CurrentModeUpdate {
 #[non_exhaustive]
 pub struct ConfigOptionUpdate {
     /// The full set of configuration options and their current values.
-    #[serde_as(deserialize_as = "VecSkipError<_>")]
+    #[serde_as(deserialize_as = "VecSkipError<_, SkipListener>")]
     pub config_options: Vec<SessionConfigOption>,
     /// 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
@@ -412,7 +412,7 @@ impl ContentChunk {
 #[non_exhaustive]
 pub struct AvailableCommandsUpdate {
     /// Commands the agent can execute
-    #[serde_as(deserialize_as = "VecSkipError<_>")]
+    #[serde_as(deserialize_as = "VecSkipError<_, SkipListener>")]
     pub available_commands: Vec<AvailableCommand>,
     /// 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
@@ -1554,7 +1554,7 @@ pub struct ClientCapabilities {
     ///
     /// The position encodings supported by the client, in order of preference.
     #[cfg(feature = "unstable_nes")]
-    #[serde_as(deserialize_as = "VecSkipError<_>")]
+    #[serde_as(deserialize_as = "VecSkipError<_, SkipListener>")]
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub position_encodings: Vec<PositionEncodingKind>,
 

src/client.rs

@@ -13,7 +13,7 @@ use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use serde_with::{DefaultOnError, VecSkipError, serde_as, skip_serializing_none};
 
-use crate::{IntoOption, Meta};
+use crate::{IntoOption, Meta, SkipListener};
 
 /// Content blocks represent displayable information in the Agent Client Protocol.
 ///
@@ -459,7 +459,7 @@ impl ResourceLink {
 #[serde(rename_all = "camelCase")]
 #[non_exhaustive]
 pub struct Annotations {
-    #[serde_as(deserialize_as = "Option<VecSkipError<_>>")]
+    #[serde_as(deserialize_as = "Option<VecSkipError<_, SkipListener>>")]
     #[serde(default)]
     pub audience: Option<Vec<Role>>,
     pub last_modified: Option<String>,

src/content.rs

@@ -8,7 +8,7 @@ use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use serde_with::{DefaultOnError, VecSkipError, serde_as, skip_serializing_none};
 
-use crate::{IntoOption, Meta, SessionId};
+use crate::{IntoOption, Meta, SessionId, SkipListener};
 
 // Method name constants
 
@@ -1099,7 +1099,7 @@ pub struct StartNesRequest {
     /// The root URI of the workspace.
     pub workspace_uri: Option<String>,
     /// The workspace folders.
-    #[serde_as(deserialize_as = "Option<VecSkipError<_>>")]
+    #[serde_as(deserialize_as = "Option<VecSkipError<_, SkipListener>>")]
     #[serde(default)]
     pub workspace_folders: Option<Vec<WorkspaceFolder>>,
     /// Repository metadata, if the workspace is a git repository.
@@ -1436,27 +1436,27 @@ impl SuggestNesRequest {
 #[non_exhaustive]
 pub struct NesSuggestContext {
     /// Recently accessed files.
-    #[serde_as(deserialize_as = "Option<VecSkipError<_>>")]
+    #[serde_as(deserialize_as = "Option<VecSkipError<_, SkipListener>>")]
     #[serde(default)]
     pub recent_files: Option<Vec<NesRecentFile>>,
     /// Related code snippets.
-    #[serde_as(deserialize_as = "Option<VecSkipError<_>>")]
+    #[serde_as(deserialize_as = "Option<VecSkipError<_, SkipListener>>")]
     #[serde(default)]
     pub related_snippets: Option<Vec<NesRelatedSnippet>>,
     /// Recent edit history.
-    #[serde_as(deserialize_as = "Option<VecSkipError<_>>")]
+    #[serde_as(deserialize_as = "Option<VecSkipError<_, SkipListener>>")]
     #[serde(default)]
     pub edit_history: Option<Vec<NesEditHistoryEntry>>,
     /// Recent user actions (typing, navigation, etc.).
-    #[serde_as(deserialize_as = "Option<VecSkipError<_>>")]
+    #[serde_as(deserialize_as = "Option<VecSkipError<_, SkipListener>>")]
     #[serde(default)]
     pub user_actions: Option<Vec<NesUserAction>>,
     /// Currently open files in the editor.
-    #[serde_as(deserialize_as = "Option<VecSkipError<_>>")]
+    #[serde_as(deserialize_as = "Option<VecSkipError<_, SkipListener>>")]
     #[serde(default)]
     pub open_files: Option<Vec<NesOpenFile>>,
     /// Current diagnostics (errors, warnings).
-    #[serde_as(deserialize_as = "Option<VecSkipError<_>>")]
+    #[serde_as(deserialize_as = "Option<VecSkipError<_, SkipListener>>")]
     #[serde(default)]
     pub diagnostics: Option<Vec<NesDiagnostic>>,
     /// The _meta property is reserved by ACP to allow clients and agents to attach additional
@@ -1757,7 +1757,7 @@ pub enum NesDiagnosticSeverity {
 #[non_exhaustive]
 pub struct SuggestNesResponse {
     /// The list of suggestions.
-    #[serde_as(deserialize_as = "VecSkipError<_>")]
+    #[serde_as(deserialize_as = "VecSkipError<_, SkipListener>")]
     pub suggestions: Vec<NesSuggestion>,
     /// 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

src/nes.rs

@@ -9,7 +9,7 @@ use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 use serde_with::{VecSkipError, serde_as, skip_serializing_none};
 
-use crate::{IntoOption, Meta};
+use crate::{IntoOption, Meta, SkipListener};
 
 /// An execution plan for accomplishing complex tasks.
 ///
@@ -28,7 +28,7 @@ pub struct Plan {
     ///
     /// When updating a plan, the agent must send a complete list of all entries
     /// with their current status. The client replaces the entire plan with each update.
-    #[serde_as(deserialize_as = "VecSkipError<_>")]
+    #[serde_as(deserialize_as = "VecSkipError<_, SkipListener>")]
     pub entries: Vec<PlanEntry>,
     /// 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

src/plan.rs

@@ -4,6 +4,8 @@
 //!
 //! - [`MaybeUndefined<T>`] — three-state: undefined (key absent), null, or value.
 //! - [`RequiredNullable<T>`] — required-but-nullable: key must be present, value may be null.
+//! - [`SkipListener`] — [`serde_with::InspectError`] hook used by every
+//!   `VecSkipError` call site in the protocol types.
 //!
 //! ## Builder traits
 //!
@@ -22,6 +24,79 @@ use std::{
 use schemars::JsonSchema;
 use serde::{Deserialize, Deserializer, Serialize, Serializer};
 
+// ---- SkipListener ----
+
+/// Inspector passed to every `VecSkipError<_, SkipListener>` in the protocol
+/// types so that malformed list entries dropped during deserialization are
+/// surfaced to observability tooling rather than vanishing silently.
+///
+/// - With the `tracing` feature enabled, this is a zero-sized type whose
+///   [`InspectError`](serde_with::InspectError) implementation emits a
+///   [`tracing::warn!`] event on every skipped entry.
+/// - With the feature disabled (the default), it resolves to `()` — which
+///   `serde_with` ships with a no-op `InspectError` implementation — so call
+///   sites incur zero runtime cost.
+#[cfg(feature = "tracing")]
+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash)]
+#[non_exhaustive]
+pub struct SkipListener;
+
+#[cfg(feature = "tracing")]
+impl serde_with::InspectError for SkipListener {
+    fn inspect_error(error: impl serde::de::Error) {
+        tracing::warn!(
+            %error,
+            "skipped malformed list entry during deserialization",
+        );
+    }
+}
+
+/// Zero-cost stand-in for [`SkipListener`] when the `tracing` feature is
+/// disabled. Resolves to `()`, which `serde_with` already ships with a no-op
+/// `InspectError` implementation.
+#[cfg(not(feature = "tracing"))]
+pub type SkipListener = ();
+
+#[cfg(test)]
+mod skip_listener_tests {
+    use std::cell::Cell;
+
+    use serde::{Deserialize, Serialize};
+    use serde_json::json;
+    use serde_with::{VecSkipError, serde_as};
+
+    thread_local! {
+        static SKIP_COUNT: Cell<u32> = const { Cell::new(0) };
+    }
+
+    /// Test-only inspector that counts skipped entries.
+    struct CountingListener;
+
+    impl serde_with::InspectError for CountingListener {
+        fn inspect_error(_error: impl serde::de::Error) {
+            SKIP_COUNT.with(|c| c.set(c.get() + 1));
+        }
+    }
+
+    #[serde_as]
+    #[derive(Serialize, Deserialize, Debug, PartialEq)]
+    struct Wrapper {
+        #[serde_as(deserialize_as = "VecSkipError<_, CountingListener>")]
+        values: Vec<u32>,
+    }
+
+    #[test]
+    fn inspector_runs_for_each_skipped_entry() {
+        SKIP_COUNT.with(|c| c.set(0));
+
+        let input = json!({"values": [1, "oops", 2, {}, 3]});
+        let wrapper: Wrapper = serde_json::from_value(input).unwrap();
+
+        assert_eq!(wrapper.values, vec![1, 2, 3]);
+        assert_eq!(SKIP_COUNT.with(Cell::get), 2);
+    }
+}
+
 // ---- IntoOption ----
 
 /// Utility trait for builder methods for optional values.