feat!: Update Message.Role enum

[jmesnil]

Align the enum values with the protobuf definition to simplify the serialiazition. Remove the string representation to rely directly on the enum textual serialization.

Remove the nullabitily of the Message role fied. If not present, it will be mapped to the ROLE_UNSPECIFIED. Remove the RoleTypeAdapter as the GSON serialization is handled automatically from the enum.

This fixes #661

[gemini-code-assist]

Summary of Changes

Hello @jmesnil, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a breaking change by refactoring the Message.Role enum to standardize its values and simplify JSON serialization. The primary goal is to align the enum with protobuf definitions, which streamlines data handling and removes the need for custom serialization adapters. This change also improves robustness by making the message role non-nullable, ensuring that missing roles default to an UNSPECIFIED state rather than causing errors during deserialization.

Highlights

• Message.Role Enum Refactoring: The Message.Role enum has been updated to align with protobuf definitions, changing USER to ROLE_USER and AGENT to ROLE_AGENT. A new ROLE_UNSPECIFIED value has been introduced.
• Simplified JSON Serialization: The custom RoleTypeAdapter for Message.Role has been removed from JsonUtil, allowing Gson to handle enum serialization directly using their names (e.g., ROLE_USER instead of user). The asString() method was also removed from the enum.
• Non-nullable Message Role: The Message.role field is now non-nullable. If a role is missing during SendMessageRequest deserialization, it will default to ROLE_UNSPECIFIED instead of causing a deserialization failure.
• Codebase-wide Updates: All references to the old Message.Role.USER and Message.Role.AGENT values across the client, server, and test modules have been updated to Message.Role.ROLE_USER and Message.Role.ROLE_AGENT respectively.
• gRPC Mapper Alignment: The RoleMapper in spec-grpc has been adjusted to reflect the new enum values and handle the ROLE_UNSPECIFIED mapping correctly between domain and protobuf representations.

Changelog

• client/base/src/main/java/io/a2a/A2A.java
  • Updated Message.Role enum references from USER to ROLE_USER and AGENT to ROLE_AGENT in message creation methods.
• client/base/src/test/java/io/a2a/A2ATest.java
  • Updated Message.Role enum references in test assertions and message builders.
• client/base/src/test/java/io/a2a/client/AuthenticationAuthorizationTest.java
  • Updated Message.Role enum reference in message builder for test setup.
• client/base/src/test/java/io/a2a/client/ClientTaskManagerTest.java
  • Updated Message.Role enum references in message builders for various test cases.
• client/transport/jsonrpc/src/test/java/io/a2a/client/transport/jsonrpc/JSONRPCTransportStreamingTest.java
  • Updated Message.Role enum references in message builders and assertions.
• client/transport/jsonrpc/src/test/java/io/a2a/client/transport/jsonrpc/JSONRPCTransportTest.java
  • Updated Message.Role enum references in message builders and assertions.
• client/transport/jsonrpc/src/test/java/io/a2a/client/transport/jsonrpc/sse/SSEEventListenerTest.java
  • Updated Message.Role enum reference in message assertions.
• client/transport/rest/src/test/java/io/a2a/client/transport/rest/RestTransportTest.java
  • Updated Message.Role enum references in message builders and assertions.
• client/transport/rest/src/test/java/io/a2a/client/transport/rest/sse/SSEEventListenerTest.java
  • Updated Message.Role enum reference in message assertions.
• client/transport/spi/src/test/java/io/a2a/client/transport/spi/sse/SSEEventListenerTest.java
  • Updated Message.Role enum references in message creation for tests.
• examples/cloud-deployment/server/src/test/java/io/a2a/examples/cloud/A2ACloudExampleClient.java
  • Updated Message.Role enum references in message builders.
• extras/opentelemetry/client/src/main/java/io/a2a/extras/opentelemetry/client/OpenTelemetryClientTransport.java
  • Updated attribute setting for GENAI_ROLE to use role.name() instead of role.asString().
• extras/opentelemetry/client/src/test/java/io/a2a/extras/opentelemetry/client/OpenTelemetryClientTransportTest.java
  • Updated Message.Role enum reference in message builder.
• extras/opentelemetry/server/src/main/java/io/a2a/extras/opentelemetry/OpenTelemetryRequestHandlerDecorator.java
  • Updated attribute setting for GENAI_ROLE to use role.name() instead of role.asString().
• extras/opentelemetry/server/src/test/java/io/a2a/extras/opentelemetry/OpenTelemetryRequestHandlerDecoratorTest.java
  • Updated Message.Role enum references in message builders for tests.
• extras/push-notification-config-store-database-jpa/src/test/java/io/a2a/extras/pushnotificationconfigstore/database/jpa/JpaDatabasePushNotificationConfigStoreIntegrationTest.java
  • Updated Message.Role enum references in message builders.
• extras/queue-manager-replicated/core/src/test/java/io/a2a/extras/queuemanager/replicated/core/EventSerializationTest.java
  • Updated Message.Role enum reference in message builder for serialization tests.
• extras/queue-manager-replicated/tests-single-instance/src/test/java/io/a2a/extras/queuemanager/replicated/tests/KafkaReplicationIntegrationTest.java
  • Updated Message.Role enum references in message builders for Kafka replication tests.
• extras/task-store-database-jpa/src/test/java/io/a2a/extras/taskstore/database/jpa/JpaDatabaseTaskStoreIntegrationTest.java
  • Updated Message.Role enum references in message builders.
• extras/task-store-database-jpa/src/test/java/io/a2a/extras/taskstore/database/jpa/JpaDatabaseTaskStoreTest.java
  • Updated Message.Role enum references in message builders and assertions for task history tests.
• jsonrpc-common/src/main/java/io/a2a/jsonrpc/common/json/JsonUtil.java
  • Removed the TaskState import.
  • Removed the custom RoleTypeAdapter class and its registration from the Gson builder.
• jsonrpc-common/src/test/java/io/a2a/jsonrpc/common/json/StreamingEventKindSerializationTest.java
  • Updated Message.Role enum references and JSON string literals to reflect new enum names.
  • Modified test to assert that a missing role now defaults to ROLE_UNSPECIFIED instead of throwing an error during deserialization.
• jsonrpc-common/src/test/java/io/a2a/jsonrpc/common/json/TaskSerializationTest.java
  • Updated Message.Role enum references and JSON string literals in task serialization tests.
• server-common/src/main/java/io/a2a/server/tasks/AgentEmitter.java
  • Updated Message.Role enum references in message builders.
• server-common/src/test/java/io/a2a/server/agentexecution/RequestContextTest.java
  • Updated Message.Role enum references in message builders for request context tests.
• server-common/src/test/java/io/a2a/server/events/EventConsumerTest.java
  • Updated JSON string literal for message role from agent to ROLE_AGENT.
• server-common/src/test/java/io/a2a/server/events/EventQueueTest.java
  • Updated JSON string literal for message role from agent to ROLE_AGENT.
• server-common/src/test/java/io/a2a/server/requesthandlers/AbstractA2ARequestHandlerTest.java
  • Updated Message.Role enum reference in message builder.
• server-common/src/test/java/io/a2a/server/tasks/AgentEmitterTest.java
  • Updated AGENT import to ROLE_AGENT and replaced AGENT with ROLE_AGENT in message builders and assertions.
• server-common/src/test/java/io/a2a/server/tasks/PushNotificationSenderTest.java
  • Updated Message.Role enum reference in message builder.
• server-common/src/test/java/io/a2a/server/tasks/ResultAggregatorTest.java
  • Updated Message.Role enum references in message creation for tests.
• server-common/src/test/java/io/a2a/server/tasks/TaskManagerTest.java
  • Updated Message.Role enum references in message builders for task manager tests.
• spec-grpc/src/main/java/io/a2a/grpc/mapper/RoleMapper.java
  • Added import for io.a2a.grpc.Role.
  • Updated comments to reflect new enum names (ROLE_USER, ROLE_AGENT, ROLE_UNSPECIFIED).
  • Modified toProto and fromProto methods to directly map new enum values and handle ROLE_UNSPECIFIED without null checks.
• spec-grpc/src/test/java/io/a2a/grpc/mapper/StreamResponseMapperTest.java
  • Updated Message.Role enum references in message builders and assertions.
• spec-grpc/src/test/java/io/a2a/grpc/utils/JSONRPCUtilsTest.java
  • Added imports for io.a2a.grpc.Role and io.a2a.spec.Message.
  • Refactored testParseMissingField_ThrowsInvalidParamsError to testParseMissingRoleGivesROLE_UNSPECIFIED to reflect new deserialization behavior.
• spec-grpc/src/test/java/io/a2a/grpc/utils/ToProtoTest.java
  • Updated Message.Role enum references in message builders.
• spec/src/main/java/io/a2a/spec/Message.java
  • Refactored Message.Role enum: USER renamed to ROLE_USER, AGENT renamed to ROLE_AGENT, and ROLE_UNSPECIFIED added.
  • Removed the role field and asString() method from the Message.Role enum.
  • Removed @Nullable annotations from several record components in the Message class for stylistic consistency.
• tests/server-common/src/test/java/io/a2a/server/apps/common/AbstractA2AServerTest.java
  • Updated Message.Role enum reference in message builder.
• transport/jsonrpc/src/test/java/io/a2a/transport/jsonrpc/handler/JSONRPCHandlerTest.java
  • Updated Message.Role enum reference in message builder.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[jmesnil]

/gemini review

[gemini-code-assist]

Code Review

This pull request effectively updates the Message.Role enum to align with the protobuf definition, which simplifies serialization by removing the custom RoleTypeAdapter. The changes are consistently applied across the codebase, including all tests and usages in the OpenTelemetry instrumentation. The new behavior of defaulting a missing role to ROLE_UNSPECIFIED is also correctly implemented and tested.

I have one minor suggestion to improve a test case by using a more robust assertion method. Overall, this is a solid refactoring that improves code clarity and maintainability.

[gemini-code-assist]

Code Review

This pull request is a well-executed breaking change that aligns the Message.Role enum with its protobuf definition, simplifying serialization and making the role field non-nullable. The change correctly defaults a missing role to ROLE_UNSPECIFIED during SendMessageRequest deserialization. The removal of the custom GSON RoleTypeAdapter and the updates to RoleMapper are consistent with this goal. The extensive updates across the codebase, especially in tests, demonstrate a thorough application of this change.

[jmesnil]

/gemini review

[gemini-code-assist]

Code Review

This pull request refactors the Message.Role enum to align with the protobuf definition, which simplifies serialization logic. The changes are propagated throughout the codebase, including tests and examples, which is great. The custom GSON RoleTypeAdapter is correctly removed. I've found one critical issue in the gRPC mapping logic that could lead to a NullPointerException. Please see my detailed comment.

[jmesnil]

@gemini-code-assist what's your detailed comment?

[gemini-code-assist]

Code Review

This pull request successfully updates the Message.Role enum to align with the protobuf definition, which simplifies serialization logic. The changes are consistently applied throughout the codebase, including the removal of the custom RoleTypeAdapter. I've found one critical issue in the RoleMapper implementation that could lead to runtime exceptions due to incorrect null handling for the now non-nullable role field. Please see the detailed comment.