fix(core): preserve legitimate falsy values in _clean_empty (a2aproject#713)

# Description

Thank you for opening a Pull Request!
Before submitting your PR, there are a few things you can do to make
sure it goes smoothly:

- [x] Follow the [`CONTRIBUTING`
Guide](https://github.com/a2aproject/a2a-python/blob/main/CONTRIBUTING.md).
- [x] Make your Pull Request title in the
<https://www.conventionalcommits.org/> specification.
- Important Prefixes for
[release-please](https://github.com/googleapis/release-please):
- `fix:` which represents bug fixes, and correlates to a
[SemVer](https://semver.org/) patch.
- `feat:` represents a new feature, and correlates to a SemVer minor.
- `feat!:`, or `fix!:`, `refactor!:`, etc., which represent a breaking
change (indicated by the `!`) and will result in a SemVer major.
- [x] Ensure the tests and linter pass (Run `bash scripts/format.sh`
from the repository root to format)
- [x] Appropriate docs were updated (if necessary)

Fixes a2aproject#692 🦕

## Problem

`_clean_empty` uses a truthiness check (`if v`) that drops legitimate
falsy values like `0`, `False`, and `0.0` alongside the intended empties
(`''`, `[]`, `{}`).

This affects `canonicalize_agent_card()` — the only caller — which
produces canonical JSON for signature verification (RFC 8785). An
`AgentCard` with e.g. `AgentCapabilities(streaming=False)` would have
the field silently stripped, losing the distinction between "explicitly
disabled" and "unspecified".

## Fix

Restructured `_clean_empty` so that only empty strings are converted to
`None` at the leaf level, and empty containers collapse naturally via
`or None` after their children are cleaned. The filter becomes `if v is
not None`, which only catches values the function itself converted —
`0`, `False`, and `0.0` never go through any conversion and flow through
unchanged.

### Alternatives considered

If maintainers prefer a different style, happy to switch to either:

- Inline sentinel: `if v not in (None, '', [], {})` directly in the
comprehensions, keeping the original structure with a fixed filter.
- Helper predicate: extract an `_is_empty(v)` function and use `if not
_is_empty(v)` as the filter in both dict and list comprehensions.

## Tests

Parametrized tests covering empty removal, falsy value preservation,
mixed cases, non-mutation, and a regression test confirming
`streaming=False` survives in `canonicalize_agent_card` output. Happy to
trim test cases if seen as excessive.

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: cchinchilla-dev

src/a2a/utils/helpers.py

@@ -350,14 +350,20 @@ def are_modalities_compatible(
 def _clean_empty(d: Any) -> Any:
     """Recursively remove empty strings, lists and dicts from a dictionary."""
     if isinstance(d, dict):
-        cleaned_dict: dict[Any, Any] = {
-            k: _clean_empty(v) for k, v in d.items()
+        cleaned_dict = {
+            k: cleaned_v
+            for k, v in d.items()
+            if (cleaned_v := _clean_empty(v)) is not None
         }
-        return {k: v for k, v in cleaned_dict.items() if v}
+        return cleaned_dict or None
     if isinstance(d, list):
-        cleaned_list: list[Any] = [_clean_empty(v) for v in d]
-        return [v for v in cleaned_list if v]
-    return d if d not in ['', [], {}] else None
+        cleaned_list = [
+            cleaned_v for v in d if (cleaned_v := _clean_empty(v)) is not None
+        ]
+        return cleaned_list or None
+    if isinstance(d, str) and not d:
+        return None
+    return d
 
 
 def canonicalize_agent_card(agent_card: AgentCard) -> str:

tests/utils/test_helpers.py

@@ -6,11 +6,11 @@
 import pytest
 
 from a2a.types import (
-    Artifact,
+    AgentCapabilities,
     AgentCard,
     AgentCardSignature,
-    AgentCapabilities,
     AgentSkill,
+    Artifact,
     Message,
     MessageSendParams,
     Part,
@@ -22,12 +22,13 @@
 )
 from a2a.utils.errors import ServerError
 from a2a.utils.helpers import (
+    _clean_empty,
     append_artifact_to_task,
     are_modalities_compatible,
     build_text_artifact,
+    canonicalize_agent_card,
     create_task_obj,
     validate,
-    canonicalize_agent_card,
 )
 
 
@@ -380,3 +381,98 @@ def test_canonicalize_agent_card():
     )
     result = canonicalize_agent_card(agent_card)
     assert result == expected_jcs
+
+
+def test_canonicalize_agent_card_preserves_false_capability():
+    """Regression #692: streaming=False must not be stripped from canonical JSON."""
+    card = AgentCard(
+        **{
+            **SAMPLE_AGENT_CARD,
+            'capabilities': AgentCapabilities(
+                streaming=False,
+                push_notifications=True,
+            ),
+        }
+    )
+    result = canonicalize_agent_card(card)
+    assert '"streaming":false' in result
+
+
+@pytest.mark.parametrize(
+    'input_val',
+    [
+        pytest.param({'a': ''}, id='empty-string'),
+        pytest.param({'a': []}, id='empty-list'),
+        pytest.param({'a': {}}, id='empty-dict'),
+        pytest.param({'a': {'b': []}}, id='nested-empty'),
+        pytest.param({'a': '', 'b': [], 'c': {}}, id='all-empties'),
+        pytest.param({'a': {'b': {'c': ''}}}, id='deeply-nested'),
+    ],
+)
+def test_clean_empty_removes_empties(input_val):
+    """_clean_empty removes empty strings, lists, and dicts recursively."""
+    assert _clean_empty(input_val) is None
+
+
+def test_clean_empty_top_level_list_becomes_none():
+    """Top-level list that becomes empty after cleaning should return None."""
+    assert _clean_empty(['', {}, []]) is None
+
+
+@pytest.mark.parametrize(
+    'input_val,expected',
+    [
+        pytest.param({'retries': 0}, {'retries': 0}, id='int-zero'),
+        pytest.param({'enabled': False}, {'enabled': False}, id='bool-false'),
+        pytest.param({'score': 0.0}, {'score': 0.0}, id='float-zero'),
+        pytest.param([0, 1, 2], [0, 1, 2], id='zero-in-list'),
+        pytest.param([False, True], [False, True], id='false-in-list'),
+        pytest.param(
+            {'config': {'max_retries': 0, 'name': 'agent'}},
+            {'config': {'max_retries': 0, 'name': 'agent'}},
+            id='nested-zero',
+        ),
+    ],
+)
+def test_clean_empty_preserves_falsy_values(input_val, expected):
+    """_clean_empty preserves legitimate falsy values (0, False, 0.0)."""
+    assert _clean_empty(input_val) == expected
+
+
+@pytest.mark.parametrize(
+    'input_val,expected',
+    [
+        pytest.param(
+            {'count': 0, 'label': '', 'items': []},
+            {'count': 0},
+            id='falsy-with-empties',
+        ),
+        pytest.param(
+            {'a': 0, 'b': 'hello', 'c': False, 'd': ''},
+            {'a': 0, 'b': 'hello', 'c': False},
+            id='mixed-types',
+        ),
+        pytest.param(
+            {'name': 'agent', 'retries': 0, 'tags': [], 'desc': ''},
+            {'name': 'agent', 'retries': 0},
+            id='realistic-mixed',
+        ),
+    ],
+)
+def test_clean_empty_mixed(input_val, expected):
+    """_clean_empty handles mixed empty and falsy values correctly."""
+    assert _clean_empty(input_val) == expected
+
+
+def test_clean_empty_does_not_mutate_input():
+    """_clean_empty should not mutate the original input object."""
+    original = {'a': '', 'b': 1, 'c': {'d': ''}}
+    original_copy = {
+        'a': '',
+        'b': 1,
+        'c': {'d': ''},
+    }
+
+    _clean_empty(original)
+
+    assert original == original_copy