feat!: Rework error classes for spec 1.0 update

[kabir]

Test the errors that were introduced since last time

This also renames some error classes

Fixes #501

[gemini-code-assist]

Summary of Changes

Hello @kabir, 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 refines the error handling and introduces robust protocol versioning to align with the A2A spec 1.0. It establishes a mechanism for clients to declare their protocol version and required extensions, which are then validated server-side. The changes ensure that communication between clients and agents adheres to specified compatibility rules and provides clearer, more structured error reporting for protocol-related issues.

Highlights

• Error Class Rework: Reworked error classes for A2A spec 1.0, including renaming AuthenticatedExtendedCardNotConfiguredError to ExtendedCardNotConfiguredError and introducing new error types: ExtensionSupportRequiredError and VersionNotSupportedError.
• Protocol Versioning: Introduced the X-A2A-Version header to allow clients to specify the A2A protocol version they are using, enabling better compatibility management.
• Server-Side Validation: Implemented server-side validation for both the X-A2A-Version header (ensuring major version compatibility) and required extensions (throwing ExtensionSupportRequiredError if not declared by the client).
• Comprehensive Error Mapping and Testing: Updated GrpcErrorMapper and RestErrorMapper to correctly handle the new error types and added extensive unit tests to verify error unmarshalling across gRPC, JSON-RPC, and REST transports.
• A2AProtocolError Base Class: Introduced A2AProtocolError as a new base class for protocol-specific errors, which now includes a URL field for more descriptive error information.

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. ↩

[gemini-code-assist]

Code Review

This pull request is a significant and well-executed refactoring of the error handling mechanism. It introduces a new A2AProtocolError base class, renames AuthenticatedExtendedCardNotConfiguredError to ExtendedCardNotConfiguredError, and adds new ExtensionSupportRequiredError and VersionNotSupportedError types. These changes are consistently applied across all transport layers (gRPC, JSON-RPC, REST), improving clarity and alignment with the A2A specification. The addition of server-side validation for protocol versions and required extensions is a major improvement to the robustness of the server implementation. The test coverage for these new features is excellent, with comprehensive tests added for all transport layers. The identified minor areas for improvement related to code cleanup and consistency remain valid.

[kabir]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a significant and well-executed rework of the error classes to align with the spec 1.0 update. Key changes include renaming AuthenticatedExtendedCardNotConfiguredError to ExtendedCardNotConfiguredError, and introducing new errors like ExtensionSupportRequiredError and VersionNotSupportedError. A new base class A2AProtocolError is added to associate protocol errors with a documentation URL, which is a great improvement for developers.

The changes are consistently applied across different transport layers (gRPC, REST, JSON-RPC), and the new validation logic for protocol versions and required extensions is correctly integrated into the request handlers. The addition of comprehensive tests for the new error mappings and validation logic is commendable.

My feedback focuses on improving the consistency of gRPC status code mappings for some of the new and updated error types to better align with gRPC best practices. Overall, this is a high-quality contribution that enhances the robustness and clarity of error handling in the SDK.