feat(compat): Improve compatibility code.

Replaces the dynamic string manipulation for TaskState enum mapping
with static bidirectional dictionaries. This is more readable, slightly
faster, and safer.

Author: bartek-w

.github/actions/spelling/allow.txt

@@ -86,6 +86,7 @@ notif
 npx
 oauthoidc
 oidc
+Oneof
 OpenAPI
 openapiv
 openapiv2

.github/actions/spelling/expect.txt

@@ -22,7 +22,8 @@ sed 's/import a2a_pb2 as a2a__pb2/from . import a2a_pb2 as a2a__pb2/g' src/a2a/t
 
 # Download legacy v0.3 compatibility protobuf code
 echo "Downloading legacy v0.3 proto file..."
-curl -o src/a2a/compat/v0_3/a2a_v0_3.proto https://raw.githubusercontent.com/a2aproject/A2A/a8b45dcc429a5571ef8a24c36336bf84b89bbd7f/specification/grpc/a2a.proto
+# b3b266d127dde3d1000ec103b252d1de81289e83 Is a2a.proto version from 0.3 branch with latests fixes.
+curl -o src/a2a/compat/v0_3/a2a_v0_3.proto https://raw.githubusercontent.com/a2aproject/A2A/b3b266d127dde3d1000ec103b252d1de81289e83/specification/grpc/a2a.proto
 
 # Generate legacy v0.3 compatibility protobuf code
 echo "Generating legacy v0.3 compatibility protobuf code"

scripts/gen_proto.sh

@@ -1,13 +1,30 @@
 import base64
 
-from typing import Any, cast
+from typing import Any
 
 from google.protobuf.json_format import MessageToDict, ParseDict
 
 from a2a.compat.v0_3 import types as types_v03
 from a2a.types import a2a_pb2 as pb2_v10
 
 
+_COMPAT_TO_CORE_TASK_STATE: dict[types_v03.TaskState, Any] = {
+    types_v03.TaskState.unknown: pb2_v10.TaskState.TASK_STATE_UNSPECIFIED,
+    types_v03.TaskState.submitted: pb2_v10.TaskState.TASK_STATE_SUBMITTED,
+    types_v03.TaskState.working: pb2_v10.TaskState.TASK_STATE_WORKING,
+    types_v03.TaskState.completed: pb2_v10.TaskState.TASK_STATE_COMPLETED,
+    types_v03.TaskState.failed: pb2_v10.TaskState.TASK_STATE_FAILED,
+    types_v03.TaskState.canceled: pb2_v10.TaskState.TASK_STATE_CANCELED,
+    types_v03.TaskState.input_required: pb2_v10.TaskState.TASK_STATE_INPUT_REQUIRED,
+    types_v03.TaskState.rejected: pb2_v10.TaskState.TASK_STATE_REJECTED,
+    types_v03.TaskState.auth_required: pb2_v10.TaskState.TASK_STATE_AUTH_REQUIRED,
+}
+
+_CORE_TO_COMPAT_TASK_STATE: dict[Any, types_v03.TaskState] = {
+    v: k for k, v in _COMPAT_TO_CORE_TASK_STATE.items()
+}
+
+
 def to_core_part(compat_part: types_v03.Part) -> pb2_v10.Part:
     """Converts a v0.3 Part (Pydantic model) to a v1.0 core Part (Protobuf object)."""
     core_part = pb2_v10.Part()
@@ -142,17 +159,9 @@ def to_core_task_status(
     """Convert task status to v1.0 core type."""
     core_status = pb2_v10.TaskStatus()
     if compat_status.state:
-        # map Enum string to proto enum
-        state_str = compat_status.state.value.upper()
-        if state_str == 'UNKNOWN':
-            core_status.state = pb2_v10.TaskState.TASK_STATE_UNSPECIFIED
-        else:
-            # Handle 'input-required', 'auth-required'
-            state_str = state_str.replace('-', '_')
-
-            core_status.state = cast(
-                'Any', pb2_v10.TaskState.Value(f'TASK_STATE_{state_str}')
-            )
+        core_status.state = _COMPAT_TO_CORE_TASK_STATE.get(
+            compat_status.state, pb2_v10.TaskState.TASK_STATE_UNSPECIFIED
+        )
 
     if compat_status.message:
         core_status.message.CopyFrom(to_core_message(compat_status.message))
@@ -167,16 +176,9 @@ def to_compat_task_status(
     core_status: pb2_v10.TaskStatus,
 ) -> types_v03.TaskStatus:
     """Convert task status to v0.3 compat type."""
-    state_str = (
-        pb2_v10.TaskState.Name(core_status.state)
-        .replace('TASK_STATE_', '')
-        .lower()
+    state_enum = _CORE_TO_COMPAT_TASK_STATE.get(
+        core_status.state, types_v03.TaskState.unknown
     )
-    if state_str == 'unspecified':
-        state_str = 'unknown'
-    else:
-        state_str = state_str.replace('_', '-')
-    state_enum = types_v03.TaskState(state_str)
 
     update = (
         to_compat_message(core_status.message)
@@ -380,16 +382,25 @@ def to_compat_task_status_update_event(
     core_event: pb2_v10.TaskStatusUpdateEvent,
 ) -> types_v03.TaskStatusUpdateEvent:
     """Convert task status update event to v0.3 compat type."""
+    status = (
+        to_compat_task_status(core_event.status)
+        if core_event.HasField('status')
+        else types_v03.TaskStatus(state=types_v03.TaskState.unknown)
+    )
+    final = status.state in (
+        types_v03.TaskState.completed,
+        types_v03.TaskState.canceled,
+        types_v03.TaskState.failed,
+        types_v03.TaskState.rejected,
+    )
     return types_v03.TaskStatusUpdateEvent(
         task_id=core_event.task_id,
         context_id=core_event.context_id,
-        status=to_compat_task_status(core_event.status)
-        if core_event.HasField('status')
-        else types_v03.TaskStatus(state=types_v03.TaskState.unknown),
+        status=status,
         metadata=MessageToDict(core_event.metadata)
         if core_event.HasField('metadata')
         else None,
-        final=False,  # 'final' was removed in v1.0
+        final=final,
     )
 
 

src/a2a/compat/v0_3/conversions.py

@@ -352,8 +352,8 @@ def test_push_notification_config_conversion():
     v03_config = types_v03.PushNotificationConfig(
         id='c1',
         url='http://test.com',
-        token='tok',
-        authentication=v03_auth,  # noqa: S106
+        token='tok',  # noqa: S106
+        authentication=v03_auth,
     )
 
     v10_expected = pb2_v10.PushNotificationConfig(
@@ -507,11 +507,61 @@ def test_task_status_update_event_conversion():
         context_id='c1',
         status=v03_status,
         metadata={'m': 'v'},
-        final=False,  # final is not preserved in v1.0
+        final=True,  # final is computed based on status.state
     )
     assert v03_restored == v03_expected_restored
 
 
+def test_task_status_update_event_conversion_terminal_states():
+    # Test all terminal states result in final=True
+    terminal_states = [
+        (
+            pb2_v10.TaskState.TASK_STATE_COMPLETED,
+            types_v03.TaskState.completed,
+        ),
+        (pb2_v10.TaskState.TASK_STATE_CANCELED, types_v03.TaskState.canceled),
+        (pb2_v10.TaskState.TASK_STATE_FAILED, types_v03.TaskState.failed),
+        (pb2_v10.TaskState.TASK_STATE_REJECTED, types_v03.TaskState.rejected),
+    ]
+
+    for core_st, compat_st in terminal_states:
+        v10_event = pb2_v10.TaskStatusUpdateEvent(
+            status=pb2_v10.TaskStatus(state=core_st)
+        )
+        v03_restored = to_compat_task_status_update_event(v10_event)
+        assert v03_restored.final is True
+        assert v03_restored.status.state == compat_st
+
+    # Test non-terminal states result in final=False
+    non_terminal_states = [
+        (
+            pb2_v10.TaskState.TASK_STATE_SUBMITTED,
+            types_v03.TaskState.submitted,
+        ),
+        (pb2_v10.TaskState.TASK_STATE_WORKING, types_v03.TaskState.working),
+        (
+            pb2_v10.TaskState.TASK_STATE_INPUT_REQUIRED,
+            types_v03.TaskState.input_required,
+        ),
+        (
+            pb2_v10.TaskState.TASK_STATE_AUTH_REQUIRED,
+            types_v03.TaskState.auth_required,
+        ),
+        (
+            pb2_v10.TaskState.TASK_STATE_UNSPECIFIED,
+            types_v03.TaskState.unknown,
+        ),
+    ]
+
+    for core_st, compat_st in non_terminal_states:
+        v10_event = pb2_v10.TaskStatusUpdateEvent(
+            status=pb2_v10.TaskStatus(state=core_st)
+        )
+        v03_restored = to_compat_task_status_update_event(v10_event)
+        assert v03_restored.final is False
+        assert v03_restored.status.state == compat_st
+
+
 def test_task_status_update_event_conversion_minimal():
     # v03 status is required but might be constructed empty internally
     v10_event = pb2_v10.TaskStatusUpdateEvent(task_id='t1', context_id='c1')
@@ -632,16 +682,16 @@ def test_oauth_flows_conversion_auth_code():
 def test_oauth_flows_conversion_client_credentials():
     v03_flows = types_v03.OAuthFlows(
         client_credentials=types_v03.ClientCredentialsOAuthFlow(
-            token_url='http://token2',
+            token_url='http://token2',  # noqa: S106
             scopes={'c': 'd'},
-            refresh_url='ref2',  # noqa: S106
+            refresh_url='ref2',
         )
     )
     v10_expected = pb2_v10.OAuthFlows(
         client_credentials=pb2_v10.ClientCredentialsOAuthFlow(
-            token_url='http://token2',
+            token_url='http://token2',  # noqa: S106
             scopes={'c': 'd'},
-            refresh_url='ref2',  # noqa: S106
+            refresh_url='ref2',
         )
     )
     v10_flows = to_core_oauth_flows(v03_flows)
@@ -674,16 +724,16 @@ def test_oauth_flows_conversion_implicit():
 def test_oauth_flows_conversion_password():
     v03_flows = types_v03.OAuthFlows(
         password=types_v03.PasswordOAuthFlow(
-            token_url='http://token3',
+            token_url='http://token3',  # noqa: S106
             scopes={'g': 'h'},
-            refresh_url='ref4',  # noqa: S106
+            refresh_url='ref4',
         )
     )
     v10_expected = pb2_v10.OAuthFlows(
         password=pb2_v10.PasswordOAuthFlow(
-            token_url='http://token3',
+            token_url='http://token3',  # noqa: S106
             scopes={'g': 'h'},
-            refresh_url='ref4',  # noqa: S106
+            refresh_url='ref4',
         )
     )
     v10_flows = to_core_oauth_flows(v03_flows)
@@ -730,8 +780,8 @@ def test_security_scheme_oauth2():
     v03_flows = types_v03.OAuthFlows(
         authorization_code=types_v03.AuthorizationCodeOAuthFlow(
             authorization_url='u',
-            token_url='t',
-            scopes={},  # noqa: S106
+            token_url='t',  # noqa: S106
+            scopes={},
         )
     )
     v03_scheme = types_v03.SecurityScheme(
@@ -1161,8 +1211,8 @@ def test_task_push_notification_config_conversion():
         push_notification_config=types_v03.PushNotificationConfig(
             id='c1',
             url='http://url',
-            token='tok',
-            authentication=v03_auth,  # noqa: S106
+            token='tok',  # noqa: S106
+            authentication=v03_auth,
         ),
     )
     v10_expected = pb2_v10.TaskPushNotificationConfig(
@@ -1183,8 +1233,8 @@ def test_task_push_notification_config_conversion():
         push_notification_config=types_v03.PushNotificationConfig(
             id='c1',
             url='http://url',
-            token='tok',
-            authentication=v03_auth,  # noqa: S106
+            token='tok',  # noqa: S106
+            authentication=v03_auth,
         ),
     )
     assert v03_restored == v03_expected_restored