feat(rust-only): better tolerate malformed optional fields in deserialization

Use `serde_with` helpers to default invalid optional values and
skip bad vector entries across protocol types.

Sometimes agents or clients send something not quite right. If it is an
optional field, we can fallback to best-effort and retain as much
information as possible without losing everything.

Author: benbrandt

Cargo.lock

@@ -55,6 +55,7 @@ derive_more = { version = "2", features = ["from", "display"] }
 schemars = { version = "1" }
 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"] }
 
 [lints.rust]

Cargo.toml

@@ -0,0 +1,5 @@
+allowed-duplicate-crates = [
+    "hashbrown",
+    "indexmap",
+    "schemars",
+]

clippy.toml

@@ -2919,6 +2919,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte
 </ResponseField>
 <ResponseField name="input" type={<><span><a href="#availablecommandinput">AvailableCommandInput</a></span><span> | null</span></>} >
   Input for the command if required
+
+    - Default: `null`
+
 </ResponseField>
 <ResponseField name="name" type={"string"} required>
   Command name (e.g., `create_plan`, `research_codebase`).

docs/protocol/draft/schema.mdx

@@ -1305,6 +1305,9 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/exte
 </ResponseField>
 <ResponseField name="input" type={<><span><a href="#availablecommandinput">AvailableCommandInput</a></span><span> | null</span></>} >
   Input for the command if required
+
+    - Default: `null`
+
 </ResponseField>
 <ResponseField name="name" type={"string"} required>
   Command name (e.g., `create_plan`, `research_codebase`).

docs/protocol/schema.mdx

@@ -442,6 +442,7 @@
               "type": "null"
             }
           ],
+          "default": null,
           "description": "Input for the command if required"
         },
         "name": {

schema/schema.json

@@ -789,6 +789,7 @@
               "type": "null"
             }
           ],
+          "default": null,
           "description": "Input for the command if required"
         },
         "name": {

schema/schema.unstable.json

@@ -8,6 +8,7 @@ use std::{path::PathBuf, sync::Arc};
 use derive_more::{Display, From};
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
+use serde_with::{DefaultOnError, VecSkipError, serde_as};
 
 #[cfg(feature = "unstable_elicitation")]
 use crate::elicitation::{
@@ -152,11 +153,13 @@ impl CurrentModeUpdate {
 }
 
 /// Session configuration options have been updated.
+#[serde_as]
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
 #[serde(rename_all = "camelCase")]
 #[non_exhaustive]
 pub struct ConfigOptionUpdate {
     /// The full set of configuration options and their current values.
+    #[serde_as(deserialize_as = "VecSkipError<_>")]
     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
@@ -249,6 +252,7 @@ impl SessionInfoUpdate {
 ///
 /// Context window and cost update for a session.
 #[cfg(feature = "unstable_session_usage")]
+#[serde_as]
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq)]
 #[serde(rename_all = "camelCase")]
 #[non_exhaustive]
@@ -258,7 +262,8 @@ pub struct UsageUpdate {
     /// Total context window size in tokens.
     pub size: u64,
     /// Cumulative session cost (optional).
-    #[serde(skip_serializing_if = "Option::is_none")]
+    #[serde_as(deserialize_as = "DefaultOnError")]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub cost: Option<Cost>,
     /// 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
@@ -395,11 +400,13 @@ impl ContentChunk {
 }
 
 /// Available commands are ready or have changed
+#[serde_as]
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
 #[serde(rename_all = "camelCase")]
 #[non_exhaustive]
 pub struct AvailableCommandsUpdate {
     /// Commands the agent can execute
+    #[serde_as(deserialize_as = "VecSkipError<_>")]
     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
@@ -432,6 +439,7 @@ impl AvailableCommandsUpdate {
 }
 
 /// Information about a command.
+#[serde_as]
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
 #[serde(rename_all = "camelCase")]
 #[non_exhaustive]
@@ -441,6 +449,8 @@ pub struct AvailableCommand {
     /// Human-readable description of what the command does.
     pub description: String,
     /// Input for the command if required
+    #[serde_as(deserialize_as = "DefaultOnError")]
+    #[serde(default)]
     pub input: Option<AvailableCommandInput>,
     /// 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
@@ -1473,6 +1483,7 @@ impl TerminalExitStatus {
 /// available features and methods.
 ///
 /// See protocol docs: [Client Capabilities](https://agentclientprotocol.com/protocol/initialization#client-capabilities)
+#[serde_as]
 #[derive(Default, Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
 #[serde(rename_all = "camelCase")]
 #[non_exhaustive]
@@ -1501,6 +1512,7 @@ pub struct ClientCapabilities {
     /// Elicitation capabilities supported by the client.
     /// Determines which elicitation modes the agent may use.
     #[cfg(feature = "unstable_elicitation")]
+    #[serde_as(deserialize_as = "DefaultOnError")]
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub elicitation: Option<ElicitationCapabilities>,
     /// **UNSTABLE**
@@ -1509,14 +1521,16 @@ pub struct ClientCapabilities {
     ///
     /// NES (Next Edit Suggestions) capabilities supported by the client.
     #[cfg(feature = "unstable_nes")]
-    #[serde(skip_serializing_if = "Option::is_none")]
+    #[serde_as(deserialize_as = "DefaultOnError")]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub nes: Option<ClientNesCapabilities>,
     /// **UNSTABLE**
     ///
     /// This capability is not part of the spec yet, and may be removed or changed at any point.
     ///
     /// The position encodings supported by the client, in order of preference.
     #[cfg(feature = "unstable_nes")]
+    #[serde_as(deserialize_as = "VecSkipError<_>")]
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub position_encodings: Vec<PositionEncodingKind>,
 

src/agent.rs

@@ -11,6 +11,7 @@
 
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
+use serde_with::{DefaultOnError, VecSkipError, serde_as};
 
 use crate::{IntoOption, Meta};
 
@@ -59,10 +60,12 @@ pub enum ContentBlock {
 }
 
 /// Text provided to or from an LLM.
+#[serde_as]
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
 #[non_exhaustive]
 pub struct TextContent {
-    #[serde(skip_serializing_if = "Option::is_none")]
+    #[serde_as(deserialize_as = "DefaultOnError")]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub annotations: Option<Annotations>,
     pub text: String,
     /// The _meta property is reserved by ACP to allow clients and agents to attach additional
@@ -109,11 +112,13 @@ impl<T: Into<String>> From<T> for ContentBlock {
 }
 
 /// An image provided to or from an LLM.
+#[serde_as]
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
 #[serde(rename_all = "camelCase")]
 #[non_exhaustive]
 pub struct ImageContent {
-    #[serde(skip_serializing_if = "Option::is_none")]
+    #[serde_as(deserialize_as = "DefaultOnError")]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub annotations: Option<Annotations>,
     pub data: String,
     pub mime_type: String,
@@ -165,11 +170,13 @@ impl ImageContent {
 }
 
 /// Audio provided to or from an LLM.
+#[serde_as]
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
 #[serde(rename_all = "camelCase")]
 #[non_exhaustive]
 pub struct AudioContent {
-    #[serde(skip_serializing_if = "Option::is_none")]
+    #[serde_as(deserialize_as = "DefaultOnError")]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub annotations: Option<Annotations>,
     pub data: String,
     pub mime_type: String,
@@ -212,10 +219,12 @@ impl AudioContent {
 }
 
 /// The contents of a resource, embedded into a prompt or tool call result.
+#[serde_as]
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
 #[non_exhaustive]
 pub struct EmbeddedResource {
-    #[serde(skip_serializing_if = "Option::is_none")]
+    #[serde_as(deserialize_as = "DefaultOnError")]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub annotations: Option<Annotations>,
     pub resource: EmbeddedResourceResource,
     /// The _meta property is reserved by ACP to allow clients and agents to attach additional
@@ -359,11 +368,13 @@ impl BlobResourceContents {
 }
 
 /// A resource that the server is capable of reading, included in a prompt or tool call result.
+#[serde_as]
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema)]
 #[serde(rename_all = "camelCase")]
 #[non_exhaustive]
 pub struct ResourceLink {
-    #[serde(skip_serializing_if = "Option::is_none")]
+    #[serde_as(deserialize_as = "DefaultOnError")]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub annotations: Option<Annotations>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub description: Option<String>,
@@ -442,11 +453,13 @@ impl ResourceLink {
 }
 
 /// Optional annotations for the client. The client can use annotations to inform how objects are used or displayed
+#[serde_as]
 #[derive(Debug, Clone, PartialEq, Deserialize, Serialize, JsonSchema, Default)]
 #[serde(rename_all = "camelCase")]
 #[non_exhaustive]
 pub struct Annotations {
-    #[serde(skip_serializing_if = "Option::is_none")]
+    #[serde_as(deserialize_as = "Option<VecSkipError<_>>")]
+    #[serde(default, skip_serializing_if = "Option::is_none")]
     pub audience: Option<Vec<Role>>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub last_modified: Option<String>,