fix(unstable-v2): parse nextCursor and listed session directories strictly (#2567)

* fix(unstable-v2): parse nextCursor and listed session directories strictly

* test: use assert_eq for empty checks

Author: benbrandt

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

@@ -1811,9 +1811,8 @@ pub struct ListSessionsResponse {
     #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
     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.
-    #[serde_as(deserialize_as = "DefaultOnError")]
-    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true)))]
+    /// to fetch the next page. Omitted and `null` are equivalent and mean there are no more
+    /// results.
     #[serde(default)]
     pub next_cursor: Option<SessionListCursor>,
     /// The _meta property is reserved by ACP to allow clients and agents to attach additional
@@ -1964,10 +1963,9 @@ pub struct SessionInfo {
     /// Additional workspace roots reported for this session. Each path must be absolute.
     ///
     /// When present, this is the complete ordered additional-root list reported
-    /// by the Agent. Omitted and empty values are equivalent: the response
+    /// by the Agent. Omitted, `null`, and empty values are equivalent: the response
     /// reports no additional roots.
-    #[serde_as(deserialize_as = "DefaultOnError<VecSkipError<_>>")]
-    #[cfg_attr(feature = "schemars", schemars(extend("x-deserialize-default-on-error" = true, "x-deserialize-skip-invalid-items" = true)))]
+    #[serde_as(deserialize_as = "DefaultOnNull")]
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub additional_directories: Vec<AbsolutePath>,
 
@@ -5882,6 +5880,27 @@ mod test_serialization {
         json!({ "source": "test" }).as_object().unwrap().clone()
     }
 
+    #[test]
+    fn list_sessions_cursor_and_session_directories_are_strict() {
+        for cursor in [json!(null), json!("next")] {
+            let response = json!({ "sessions": [], "nextCursor": cursor });
+            serde_json::from_value::<ListSessionsResponse>(response).unwrap();
+        }
+        let malformed = json!({ "sessions": [], "nextCursor": 42 });
+        assert!(serde_json::from_value::<ListSessionsResponse>(malformed).is_err());
+
+        let session = |dirs: serde_json::Value| json!({ "sessionId": "s", "cwd": "/w", "additionalDirectories": dirs });
+        let info: SessionInfo = serde_json::from_value(session(json!(null))).unwrap();
+        assert_eq!(info.additional_directories, Vec::<AbsolutePath>::new());
+        for bad in [json!(["/a", 42]), json!("/a")] {
+            assert!(serde_json::from_value::<SessionInfo>(session(bad)).is_err());
+        }
+        // A session with malformed directories is skipped, not truncated.
+        let response = json!({ "sessions": [session(json!(["/a", 42]))] });
+        let response: ListSessionsResponse = serde_json::from_value(response).unwrap();
+        assert_eq!(response.sessions, Vec::<SessionInfo>::new());
+    }
+
     #[test]
     fn other_fallbacks_preserve_optional_fields_verbatim() {
         let valid = json!({ "type": "_custom", "methodId": "m", "name": "M",

docs/protocol/v2/draft/schema.mdx

@@ -765,7 +765,8 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d
 </ResponseField>
 <ResponseField name="nextCursor" type={<><span><a href="#sessionlistcursor">SessionListCursor</a></span><span> | null</span></>} >
   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.
+to fetch the next page. Omitted and `null` are equivalent and mean there are no more
+results.
 </ResponseField>
 <ResponseField name="sessions" type={<a href="#sessioninfo">SessionInfo[]</a>} required>
   Array of session information objects.
@@ -6886,7 +6887,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/d
   Additional workspace roots reported for this session. Each path must be absolute.
 
 When present, this is the complete ordered additional-root list reported
-by the Agent. Omitted and empty values are equivalent: the response
+by the Agent. Omitted, `null`, and empty values are equivalent: the response
 reports no additional roots.
 
 </ResponseField>

docs/protocol/v2/draft/session-list.mdx

@@ -118,8 +118,7 @@ The Agent **MUST** respond with a list of sessions and optional pagination metad
     <ResponseField name="additionalDirectories" type="string[]">
       If the Agent advertises `session.additionalDirectories`, it
       **MAY** include this field to report the complete ordered additional-root list
-      associated with the listed session. Omitted and empty values are
-      equivalent: this `SessionInfo` response reports no additional roots.
+      associated with the listed session. Omitted, `null`, and empty values are equivalent: this `SessionInfo` response reports no additional roots.
       Clients **MUST NOT** merge this field with prior values or infer additional
       roots from agent-specific state.
     </ResponseField>
@@ -139,7 +138,8 @@ The Agent **MUST** respond with a list of sessions and optional pagination metad
 
 <ResponseField name="nextCursor" type="string">
   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.
+  parameter to fetch the next page. Omitted and `null` are equivalent and mean
+  there are no more results.
 </ResponseField>
 
 When no sessions match the criteria, the Agent **MUST** return an empty `sessions` array.

docs/protocol/v2/schema.mdx

@@ -435,7 +435,8 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e
 </ResponseField>
 <ResponseField name="nextCursor" type={<><span><a href="#sessionlistcursor">SessionListCursor</a></span><span> | null</span></>} >
   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.
+to fetch the next page. Omitted and `null` are equivalent and mean there are no more
+results.
 </ResponseField>
 <ResponseField name="sessions" type={<a href="#sessioninfo">SessionInfo[]</a>} required>
   Array of session information objects.
@@ -5905,7 +5906,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/e
   Additional workspace roots reported for this session. Each path must be absolute.
 
 When present, this is the complete ordered additional-root list reported
-by the Agent. Omitted and empty values are equivalent: the response
+by the Agent. Omitted, `null`, and empty values are equivalent: the response
 reports no additional roots.
 
 </ResponseField>

docs/protocol/v2/session-list.mdx

@@ -118,8 +118,7 @@ The Agent **MUST** respond with a list of sessions and optional pagination metad
     <ResponseField name="additionalDirectories" type="string[]">
       If the Agent advertises `session.additionalDirectories`, it
       **MAY** include this field to report the complete ordered additional-root list
-      associated with the listed session. Omitted and empty values are
-      equivalent: this `SessionInfo` response reports no additional roots.
+      associated with the listed session. Omitted, `null`, and empty values are equivalent: this `SessionInfo` response reports no additional roots.
       Clients **MUST NOT** merge this field with prior values or infer additional
       roots from agent-specific state.
     </ResponseField>
@@ -139,7 +138,8 @@ The Agent **MUST** respond with a list of sessions and optional pagination metad
 
 <ResponseField name="nextCursor" type="string">
   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.
+  parameter to fetch the next page. Omitted and `null` are equivalent and mean
+  there are no more results.
 </ResponseField>
 
 When no sessions match the criteria, the Agent **MUST** return an empty `sessions` array.

schema/v2/schema.json

@@ -4131,16 +4131,15 @@
           "x-deserialize-skip-invalid-items": true
         },
         "nextCursor": {
-          "description": "Opaque cursor token. If present, pass this in the next request's cursor parameter\nto fetch the next page. If absent, there are no more results.",
+          "description": "Opaque cursor token. If present, pass this in the next request's cursor parameter\nto fetch the next page. Omitted and `null` are equivalent and mean there are no more\nresults.",
           "anyOf": [
             {
               "$ref": "#/$defs/SessionListCursor"
             },
             {
               "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 make assumptions about values at these keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)",
@@ -4174,13 +4173,11 @@
           ]
         },
         "additionalDirectories": {
-          "description": "Additional workspace roots reported for this session. Each path must be absolute.\n\nWhen present, this is the complete ordered additional-root list reported\nby the Agent. Omitted and empty values are equivalent: the response\nreports no additional roots.",
+          "description": "Additional workspace roots reported for this session. Each path must be absolute.\n\nWhen present, this is the complete ordered additional-root list reported\nby the Agent. Omitted, `null`, and empty values are equivalent: the response\nreports no additional roots.",
           "type": "array",
           "items": {
             "$ref": "#/$defs/AbsolutePath"
-          },
-          "x-deserialize-default-on-error": true,
-          "x-deserialize-skip-invalid-items": true
+          }
         },
         "title": {
           "description": "Human-readable title for the session\n\nOmitted and `null` are equivalent and mean no title is provided.",

schema/v2/schema.unstable.json

@@ -4573,16 +4573,15 @@
           "x-deserialize-skip-invalid-items": true
         },
         "nextCursor": {
-          "description": "Opaque cursor token. If present, pass this in the next request's cursor parameter\nto fetch the next page. If absent, there are no more results.",
+          "description": "Opaque cursor token. If present, pass this in the next request's cursor parameter\nto fetch the next page. Omitted and `null` are equivalent and mean there are no more\nresults.",
           "anyOf": [
             {
               "$ref": "#/$defs/SessionListCursor"
             },
             {
               "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 make assumptions about values at these keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/draft/extensibility)",
@@ -4616,13 +4615,11 @@
           ]
         },
         "additionalDirectories": {
-          "description": "Additional workspace roots reported for this session. Each path must be absolute.\n\nWhen present, this is the complete ordered additional-root list reported\nby the Agent. Omitted and empty values are equivalent: the response\nreports no additional roots.",
+          "description": "Additional workspace roots reported for this session. Each path must be absolute.\n\nWhen present, this is the complete ordered additional-root list reported\nby the Agent. Omitted, `null`, and empty values are equivalent: the response\nreports no additional roots.",
           "type": "array",
           "items": {
             "$ref": "#/$defs/AbsolutePath"
-          },
-          "x-deserialize-default-on-error": true,
-          "x-deserialize-skip-invalid-items": true
+          }
         },
         "title": {
           "description": "Human-readable title for the session\n\nOmitted and `null` are equivalent and mean no title is provided.",