feat: Remove legacy JSON-RPC errors

[bartek-gralewicz]

Description

Update to errors usage in a2a-js. Previously, errors were based around JSON-RPC transport but since now, multiple transports are supported, errors thrown by the server should be transport agnostic.

List of changes

• Removed old src/server/error.ts.
• Replaced JSON-RPC errors with transport agnostic errors and proper mapping when errors are thrown.
• Removed as <Type> usage in grpc_transport.ts as suggested here: feat: Remove Proto Conversions #356 (comment)

Fixes (partially) #179 🦕

[gemini-code-assist]

Summary of Changes

Hello, 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 significantly refactors the error handling mechanism within the a2a-js project. The primary goal is to move away from a JSON-RPC-specific error system towards a more flexible, transport-agnostic approach. This change enables a2a-js to support multiple communication protocols (like gRPC and REST) more cleanly by centralizing error definitions and providing robust mapping logic for each transport, improving the overall maintainability and extensibility of the error handling.

Highlights

• Error System Refactor: Replaced the legacy A2AError class, which was tied to JSON-RPC, with a new set of transport-agnostic error classes.
• New Error Classes: Introduced ParseError, InvalidRequestError, MethodNotFoundError, InvalidParamsError, and InternalError to provide a standardized error hierarchy across all transports.
• Transport-Agnostic Error Mapping: Updated gRPC, JSON-RPC, and REST transport layers to map these new generic errors to their specific error formats (e.g., gRPC status codes, JSON-RPC error objects, HTTP status codes) rather than relying on a single, JSON-RPC-centric error structure.
• Type Safety Improvements: Removed as <Type> assertions in gRPC client calls, enhancing type safety.

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.

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 to decouple errors from the JSON-RPC transport layer. By removing the legacy A2AError and introducing transport-agnostic error classes, the codebase is now more robust and better prepared for multiple transport protocols. The changes have been applied consistently across all relevant files, including server-side handlers (REST, gRPC, JSON-RPC), client-side transports, and the core request handler logic. The tests have also been diligently updated to reflect these changes. Overall, this is an excellent improvement to the project's architecture and maintainability. I have one minor suggestion to improve code consistency.

[github-actions]

🧪 Code Coverage

⬇️ Download Full Report

	Main	PR	Delta
src/client/card-resolver.ts	96.82%	95.23%	🔴 -1.59%
src/client/multitransport-client.ts	97.66%	97.72%	🟢 +0.06%
src/client/transports/grpc/grpc_transport.ts	93.92%	93.6%	🔴 -0.32%
src/client/transports/json_rpc_transport.ts	62.57%	60.92%	🔴 -1.65%
src/client/transports/rest_transport.ts	85.8%	81.44%	🔴 -4.36%
src/errors.ts	78.57%	100%	🟢 +21.43%
src/server/express/json_rpc_handler.ts	90.62%	94.25%	🟢 +3.63%
src/server/express/rest_handler.ts	85.6%	89.38%	🟢 +3.78%
src/server/grpc/grpc_service.ts	68.78%	68.15%	🔴 -0.63%
src/server/push_notification/push_notification_store.ts	89.18%	83.78%	🔴 -5.40%
src/server/request_handler/default_request_handler.ts	79.69%	79.31%	🔴 -0.38%
src/server/result_manager.ts	61.7%	62.79%	🟢 +1.09%
src/server/transports/jsonrpc/jsonrpc_transport_handler.ts	76.68%	74.78%	🔴 -1.90%
src/server/transports/rest/rest_transport_handler.ts	98.78%	98.75%	🔴 -0.03%
src/types/converters/from_proto.ts	74.88%	100%	🟢 +25.12%
src/types/converters/id_decoding.ts	52%	76%	🟢 +24.00%
src/types/converters/to_proto.ts	69.38%	92.68%	🟢 +23.30%
src/json_rpc_types.ts (new)	—	0%	—
Total	81.12%	84.47%	🟢 +3.35%

Generated by coverage-comment.yml

[bartek-gralewicz]

/gemini review

[gemini-code-assist]

Code Review

The pull request successfully refactors the error handling mechanism by removing the legacy JSON-RPC specific A2AError class and introducing a set of transport-agnostic error classes (RequestMalformedError, GenericError, TaskNotFoundError, etc.). This change significantly improves the modularity and flexibility of the error system, allowing for better support of multiple transports as stated in the PR description. The updates across client and server transport handlers, as well as converters and tests, demonstrate a thorough implementation of this new error model. The removal of as <Type> assertions in grpc_transport.ts also enhances type safety.