// Analyzes and fixes A2A Transport Compatibility Kit (TCK) issues by understanding the specification, reproducing the failure, implementing the fix, and validating it works.
| name | fix-tck-issue |
| description | Analyzes and fixes A2A Transport Compatibility Kit (TCK) issues by understanding the specification, reproducing the failure, implementing the fix, and validating it works. |
| compatibility | Requires gh CLI and mvn |
| allowed-tools | Bash(gh:*) Bash(mvn:*) Bash(git:*) Bash(curl:*) Read Edit Write Glob Grep WebFetch |
main)gh issue view <issue-number> --repo a2aproject/a2a-java --json title,body,labels,url
Parse issue to identify:
TCK issues contain the spec checksum, but reading the spec is helpful if TCK lags behind or for additional context.
Fetch from https://github.com/a2aproject/A2A with specified ref (use checksum from issue or default to main):
specification/grpc/a2a.proto - for proto definitions and HTTP transcodingdocs/specification.md - for detailed protocol requirementsFocus on sections referenced in the issue.
Locate relevant code based on transport:
transport/resttransport/grpctransport/jsonrpcIdentify root cause by comparing:
Optional: If issue includes a curl/grpcurl reproducer, run it manually to validate the issue is genuine.
CRITICAL: If issue doesn't specify a single transport, you MUST create reproducers for ALL affected transports.
Issue mentions specific transport → Test that one only Issue generic or mentions "all transports" → Test HTTP+JSON, gRPC, AND JSON-RPC
Create test in appropriate module. Choose location based on test complexity:
Option A: transport/ modules (Unit Tests)* - Use when:
transport/rest/src/test/java/org/a2aproject/sdk/transport/rest/handler/RestHandlerTest.javatransport/grpc/src/test/java/org/a2aproject/sdk/transport/grpc/handler/GrpcHandlerTest.javatransport/jsonrpc/src/test/java/org/a2aproject/sdk/transport/jsonrpc/handler/JSONRPCHandlerTest.javaOption B: reference/ modules (Integration Tests)* - Use when:
reference/rest/src/test/java/.../reference/grpc/src/test/java/.../reference/jsonrpc/src/test/java/.../Reproducer requirements:
test_Issue<number>_Reproducer()Example:
@Test
public void test_Issue732_Reproducer() {
// Per spec: taskId should NOT be in request body for HTTP+JSON
String requestBody = """
{
"id": "my-config-001",
"url": "https://example.com/webhook"
}""";
HTTPRestResponse response = handler.createTaskPushNotificationConfiguration(
context, "", requestBody, taskId);
assertEquals(201, response.getStatusCode());
}
CRITICAL: You MUST run the reproducer and see it FAIL before proceeding to fix.
For transport/* modules:
mvn test -Dtest=<TestClass>#test_Issue<number>_Reproducer -pl transport/<transport>
For reference/* modules:
mvn test -Dtest=<TestClass>#test_Issue<number>_Reproducer -pl reference/<transport>
Required verification (DO NOT SKIP):
If reproducer doesn't fail as expected:
Only proceed to step 7 after confirming all reproducers fail correctly.
Make minimal code changes to fix the root cause.
If multiple transports are affected: Fix ALL of them before proceeding to verification.
Common patterns:
builder.setFieldName(pathParam)Run ALL reproducers you created in step 5.
For transport/* modules:
mvn test -Dtest=<TestClass>#test_Issue<number>_Reproducer -pl transport/<transport>
For reference/* modules:
mvn test -Dtest=<TestClass>#test_Issue<number>_Reproducer -pl reference/<transport>
Required verification:
If any reproducer still fails, debug and refine the fix.
Run full test suite for ALL modified transport modules to ensure no regressions:
mvn test -pl transport/rest,transport/jsonrpc,transport/grpc
If you also modified reference modules or only created reproducers there:
mvn test -pl reference/rest,reference/jsonrpc,reference/grpc
All existing tests must pass.
Remove ALL test methods or files created in step 5.
If you added a method to existing test class:
test_Issue<number>_Reproducer() methodIf you created a new test file:
Issue733ReproducerTest.java)Add only the impacted files (NOT the temporary reproducers):
git add <changed-files>
git commit -m "fix: <concise description>
<explanation of spec requirement and how code was fixed>
Applied to <list transports if multiple>.
Fixes #<issue-number>"
Example for multi-transport fix:
git add transport/rest/src/main/java/org/a2aproject/sdk/transport/rest/handler/RestHandler.java \
transport/jsonrpc/src/main/java/org/a2aproject/sdk/transport/jsonrpc/handler/JSONRPCHandler.java \
transport/grpc/src/main/java/org/a2aproject/sdk/transport/grpc/handler/GrpcHandler.java
git commit -m "fix: Return UnsupportedOperationError when capability is disabled
Applied to all three transports: HTTP+JSON, JSON-RPC, and gRPC.
Fixes #733"
body: "*"Proto definition with path parameters and body: "*" means:
Example proto:
rpc CreateTaskPushNotificationConfig(...) {
option (google.api.http) = {
post: "/tasks/{task_id}/pushNotificationConfigs"
body: "*"
};
}
Fix pattern:
// Extract from URL path and set in builder
builder.setTaskId(taskId);
"X is required" errors often mean:
Best for:
Test file locations:
transport/rest/src/test/java/org/a2aproject/sdk/transport/rest/handler/RestHandlerTest.javatransport/grpc/src/test/java/org/a2aproject/sdk/transport/grpc/handler/GrpcHandlerTest.javatransport/jsonrpc/src/test/java/org/a2aproject/sdk/transport/jsonrpc/handler/JSONRPCHandlerTest.javaBest for:
Structure:
reference/
├── rest/ # HTTP+JSON integration tests
├── grpc/ # gRPC integration tests
└── jsonrpc/ # JSON-RPC integration tests
Issue #732: CreateTaskPushNotificationConfig required taskId in body (HTTP+JSON only)
0833a5f5fd1b715519c0aecf9e3055e3f9f38089body: "*" means taskId from pathbuilder.setTaskId(taskId) to RestHandlerIssue #733: GetExtendedAgentCard returns wrong error when capability disabled
0833a5f5fd1b715519c0aecf9e3055e3f9f38089