refactor: modularize error handling

Author: JakubWorek

docs/migration-guide.md

@@ -269,8 +269,10 @@ tenant-prefixed routes (`/:tenant/tasks/:taskId`, etc.) and validates the
 
 The monolithic `A2AError` class with static factory methods is removed. Errors
 now form a shared transport-agnostic hierarchy — one `A2AError` base with
-semantic subclasses (`TaskNotFoundError`, `RequestMalformedError`, …) — and
-live at the SDK root, not under `/client` or `/server`:
+semantic subclasses (`TaskNotFoundError`, `RequestMalformedError`, …). They
+live at `@a2a-js/sdk/errors`; gRPC-specific error helpers live at
+`@a2a-js/sdk/errors/grpc` so consumers who don't use gRPC don't pull in
+`@bufbuild/protobuf`.
 
 ```typescript
 // v0.3
@@ -279,7 +281,7 @@ throw A2AError.taskNotFound('task-1');
 throw A2AError.invalidParams('bad input');
 
 // v1.0
-import { TaskNotFoundError, RequestMalformedError } from '@a2a-js/sdk';
+import { TaskNotFoundError, RequestMalformedError } from '@a2a-js/sdk/errors';
 throw new TaskNotFoundError({ message: 'task-1' });
 throw new RequestMalformedError({ message: 'bad input' });
 ```
@@ -296,7 +298,7 @@ Per-transport variants (`RestTaskNotFoundError`, `GrpcTaskNotFoundError`,
 API surfaces are on the base:
 
 ```typescript
-import { isRestError, TaskNotFoundError } from '@a2a-js/sdk';
+import { isRestError, TaskNotFoundError } from '@a2a-js/sdk/errors';
 
 try {
   await client.getTask({ id });
@@ -310,9 +312,16 @@ try {
 }
 ```
 
+For gRPC callers, the transport variant + guard live in a separate subpath:
+
+```typescript
+import { isGrpcError, TaskNotFoundError } from '@a2a-js/sdk/errors/grpc';
+```
+
 Error codes and gRPC/HTTP status mappings are defined in the
 [spec](https://a2a-protocol.org/v1.0.0/specification/#54-error-code-mappings)
-and live in a single registry (`A2A_ERROR_SPECS`) exported from `@a2a-js/sdk`.
+and live in a single registry (`A2A_ERROR_SPECS`) exported from
+`@a2a-js/sdk/errors`.
 
 ### 3.3 `ServerCallContext` -- Now Mandatory
 
@@ -469,11 +478,11 @@ await verify(agentCard);
 
 ## 5. Import Path Changes
 
-| v0.3 Import                                                  | v1.0 Import                                            |
-| ------------------------------------------------------------ | ------------------------------------------------------ |
-| `import { A2AClient } from '@a2a-js/sdk/client'`             | Removed -- use `ClientFactory` + `Client`              |
-| `import { TextPart, FilePart, DataPart } from '@a2a-js/sdk'` | Removed -- use `Part`                                  |
-| `import { MessageSendParams } from '@a2a-js/sdk'`            | `import { SendMessageRequest } from '@a2a-js/sdk'`     |
-| `import { TaskQueryParams } from '@a2a-js/sdk'`              | `import { GetTaskRequest } from '@a2a-js/sdk'`         |
-| `import { TaskIdParams } from '@a2a-js/sdk'`                 | `import { CancelTaskRequest } from '@a2a-js/sdk'`      |
-| `import { A2AError } from '@a2a-js/sdk/server'`              | `import { TaskNotFoundError, ... } from '@a2a-js/sdk'` |
+| v0.3 Import                                                  | v1.0 Import                                                                                                   |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
+| `import { A2AClient } from '@a2a-js/sdk/client'`             | Removed -- use `ClientFactory` + `Client`                                                                     |
+| `import { TextPart, FilePart, DataPart } from '@a2a-js/sdk'` | Removed -- use `Part`                                                                                         |
+| `import { MessageSendParams } from '@a2a-js/sdk'`            | `import { SendMessageRequest } from '@a2a-js/sdk'`                                                            |
+| `import { TaskQueryParams } from '@a2a-js/sdk'`              | `import { GetTaskRequest } from '@a2a-js/sdk'`                                                                |
+| `import { TaskIdParams } from '@a2a-js/sdk'`                 | `import { CancelTaskRequest } from '@a2a-js/sdk'`                                                             |
+| `import { A2AError } from '@a2a-js/sdk/server'`              | `import { TaskNotFoundError, ... } from '@a2a-js/sdk/errors'` (or `@a2a-js/sdk/errors/grpc` for gRPC helpers) |

package.json

@@ -15,6 +15,12 @@
   "type": "module",
   "typesVersions": {
     "*": {
+      "errors": [
+        "./dist/errors/index.d.ts"
+      ],
+      "errors/grpc": [
+        "./dist/errors/grpc/index.d.ts"
+      ],
       "server": [
         "./dist/server/index.d.ts"
       ],
@@ -56,6 +62,16 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./errors": {
+      "types": "./dist/errors/index.d.ts",
+      "import": "./dist/errors/index.js",
+      "require": "./dist/errors/index.cjs"
+    },
+    "./errors/grpc": {
+      "types": "./dist/errors/grpc/index.d.ts",
+      "import": "./dist/errors/grpc/index.js",
+      "require": "./dist/errors/grpc/index.cjs"
+    },
     "./server": {
       "types": "./dist/server/index.d.ts",
       "import": "./dist/server/index.js",
@@ -154,7 +170,7 @@
     "coverage": "vitest run --coverage",
     "generate": "curl https://raw.githubusercontent.com/google-a2a/A2A/refs/heads/main/specification/json/a2a.json > spec.json && node scripts/generateTypes.js && rm spec.json",
     "generate:compat": "curl https://raw.githubusercontent.com/a2aproject/A2A/v0.3.0/specification/json/a2a.json > compat_spec.json && node scripts/generateCompatTypes.js && rm compat_spec.json",
-    "test-build": "esbuild ./dist/client/index.js ./dist/server/index.js ./dist/index.js ./dist/compat/v0_3/index.js ./dist/compat/v0_3/client/index.js ./dist/compat/v0_3/server/index.js --bundle --platform=neutral --outdir=dist/tmp-checks --outbase=./dist",
+    "test-build": "esbuild ./dist/client/index.js ./dist/server/index.js ./dist/index.js ./dist/errors/index.js ./dist/errors/grpc/index.js ./dist/compat/v0_3/index.js ./dist/compat/v0_3/client/index.js ./dist/compat/v0_3/server/index.js --bundle --platform=neutral --outdir=dist/tmp-checks --outbase=./dist",
     "itk-agent": "tsx itk/itk_agent.ts"
   },
   "dependencies": {

src/client/transports/grpc/grpc_transport.ts

@@ -24,7 +24,7 @@ import { RequestOptions } from '../../multitransport-client.js';
 import { Transport, TransportFactory } from '../transport.js';
 import { FromProto } from '../../../types/converters/from_proto.js';
 
-import { fromGrpcError } from '../../../errors/index.js';
+import { fromGrpcError } from '../../../errors/grpc/index.js';
 import { LegacyGrpcTransport } from '../../../compat/v0_3/client/transports/grpc/index.js';
 import { isLegacyVersion } from '../../../version_utils.js';
 import { pickMatchingInterface } from '../pick_interface.js';

src/compat/v0_3/client/transports/grpc/grpc_transport.ts

@@ -17,7 +17,8 @@
 
 import * as grpc from '@grpc/grpc-js';
 import { TransportProtocolName } from '../../../../../core.js';
-import { fromGrpcError, UnsupportedOperationError } from '../../../../../errors/index.js';
+import { UnsupportedOperationError } from '../../../../../errors/index.js';
+import { fromGrpcError } from '../../../../../errors/grpc/index.js';
 import { A2A_LEGACY_PROTOCOL_VERSION } from '../../../../../constants.js';
 import type { SendMessageResult } from '../../../../../index.js';
 import type { RequestOptions } from '../../../../../client/multitransport-client.js';

src/compat/v0_3/server/grpc/grpc_service.ts

@@ -39,13 +39,12 @@ import { UserBuilder } from './common.js';
 import { A2A_VERSION_HEADER, HTTP_EXTENSION_HEADER } from '../../../../constants.js';
 import { LEGACY_HTTP_EXTENSION_HEADER } from '../../constants.js';
 import {
+  A2A_STATUS_CODE,
   A2AError,
-  buildGrpcErrorMetadata,
-  GRPC_STATUS,
-  grpcStatusFor,
   InvalidAgentResponseError,
   isJsonRpcError,
 } from '../../../../errors/index.js';
+import { buildGrpcErrorMetadata, grpcStatusFor } from '../../../../errors/grpc/index.js';
 import { validateVersion } from '../../../../server/version.js';
 import { FromProto } from '../../types/converters/from_proto.js';
 import { ToProto } from '../../types/converters/to_proto.js';
@@ -448,7 +447,7 @@ const mapToError = (error: unknown): Partial<grpc.ServiceError> => {
   } else if (error instanceof A2AError) {
     code = grpcStatusFor(error);
   } else {
-    code = GRPC_STATUS.UNKNOWN;
+    code = A2A_STATUS_CODE.UNKNOWN;
   }
   const message = error instanceof Error ? error.message : 'Internal server error';
   const result: Partial<grpc.ServiceError> = { code, details: message };

src/errors/base.ts

@@ -45,8 +45,14 @@ export const HTTP_STATUS = {
   NOT_IMPLEMENTED: 501,
 } as const;
 
-/** gRPC status codes referenced by the registry. Mirrors `@grpc/grpc-js`'s `status` enum. */
-export const GRPC_STATUS = {
+/**
+ * Canonical numeric status codes used by the semantic-error registry
+ * to describe the spec-mapped status per §5.4. The numeric namespace
+ * matches gRPC's `status` enum (so the gRPC transport can emit them
+ * directly) and the string form (see {@link A2A_STATUS_NAME}) fills
+ * the REST body's `status` field per §11.6.
+ */
+export const A2A_STATUS_CODE = {
   OK: 0,
   CANCELLED: 1,
   UNKNOWN: 2,
@@ -66,25 +72,28 @@ export const GRPC_STATUS = {
   UNAUTHENTICATED: 16,
 } as const;
 
-/** Names of the gRPC status codes, for `google.rpc.Status.status`. */
-export const GRPC_STATUS_NAME: Readonly<Record<number, string>> = {
-  [GRPC_STATUS.OK]: 'OK',
-  [GRPC_STATUS.CANCELLED]: 'CANCELLED',
-  [GRPC_STATUS.UNKNOWN]: 'UNKNOWN',
-  [GRPC_STATUS.INVALID_ARGUMENT]: 'INVALID_ARGUMENT',
-  [GRPC_STATUS.DEADLINE_EXCEEDED]: 'DEADLINE_EXCEEDED',
-  [GRPC_STATUS.NOT_FOUND]: 'NOT_FOUND',
-  [GRPC_STATUS.ALREADY_EXISTS]: 'ALREADY_EXISTS',
-  [GRPC_STATUS.PERMISSION_DENIED]: 'PERMISSION_DENIED',
-  [GRPC_STATUS.RESOURCE_EXHAUSTED]: 'RESOURCE_EXHAUSTED',
-  [GRPC_STATUS.FAILED_PRECONDITION]: 'FAILED_PRECONDITION',
-  [GRPC_STATUS.ABORTED]: 'ABORTED',
-  [GRPC_STATUS.OUT_OF_RANGE]: 'OUT_OF_RANGE',
-  [GRPC_STATUS.UNIMPLEMENTED]: 'UNIMPLEMENTED',
-  [GRPC_STATUS.INTERNAL]: 'INTERNAL',
-  [GRPC_STATUS.UNAVAILABLE]: 'UNAVAILABLE',
-  [GRPC_STATUS.DATA_LOSS]: 'DATA_LOSS',
-  [GRPC_STATUS.UNAUTHENTICATED]: 'UNAUTHENTICATED',
+/**
+ * String form of {@link A2A_STATUS_CODE}, used in the REST body's
+ * `status` field per §11.6. Names follow the gRPC enum form.
+ */
+export const A2A_STATUS_NAME: Readonly<Record<number, string>> = {
+  [A2A_STATUS_CODE.OK]: 'OK',
+  [A2A_STATUS_CODE.CANCELLED]: 'CANCELLED',
+  [A2A_STATUS_CODE.UNKNOWN]: 'UNKNOWN',
+  [A2A_STATUS_CODE.INVALID_ARGUMENT]: 'INVALID_ARGUMENT',
+  [A2A_STATUS_CODE.DEADLINE_EXCEEDED]: 'DEADLINE_EXCEEDED',
+  [A2A_STATUS_CODE.NOT_FOUND]: 'NOT_FOUND',
+  [A2A_STATUS_CODE.ALREADY_EXISTS]: 'ALREADY_EXISTS',
+  [A2A_STATUS_CODE.PERMISSION_DENIED]: 'PERMISSION_DENIED',
+  [A2A_STATUS_CODE.RESOURCE_EXHAUSTED]: 'RESOURCE_EXHAUSTED',
+  [A2A_STATUS_CODE.FAILED_PRECONDITION]: 'FAILED_PRECONDITION',
+  [A2A_STATUS_CODE.ABORTED]: 'ABORTED',
+  [A2A_STATUS_CODE.OUT_OF_RANGE]: 'OUT_OF_RANGE',
+  [A2A_STATUS_CODE.UNIMPLEMENTED]: 'UNIMPLEMENTED',
+  [A2A_STATUS_CODE.INTERNAL]: 'INTERNAL',
+  [A2A_STATUS_CODE.UNAVAILABLE]: 'UNAVAILABLE',
+  [A2A_STATUS_CODE.DATA_LOSS]: 'DATA_LOSS',
+  [A2A_STATUS_CODE.UNAUTHENTICATED]: 'UNAUTHENTICATED',
 };
 
 /** A structured detail object included in error responses. */
@@ -177,87 +186,87 @@ const specs: A2AErrorSpec[] = [
     name: 'TaskNotFoundError',
     reason: 'TASK_NOT_FOUND',
     code: A2A_ERROR_CODE.TASK_NOT_FOUND,
-    grpcStatus: GRPC_STATUS.NOT_FOUND,
+    grpcStatus: A2A_STATUS_CODE.NOT_FOUND,
     httpStatus: HTTP_STATUS.NOT_FOUND,
     defaultMessage: 'Task not found',
   },
   {
     name: 'TaskNotCancelableError',
     reason: 'TASK_NOT_CANCELABLE',
     code: A2A_ERROR_CODE.TASK_NOT_CANCELABLE,
-    grpcStatus: GRPC_STATUS.FAILED_PRECONDITION,
+    grpcStatus: A2A_STATUS_CODE.FAILED_PRECONDITION,
     httpStatus: HTTP_STATUS.BAD_REQUEST,
     defaultMessage: 'Task cannot be canceled',
   },
   {
     name: 'PushNotificationNotSupportedError',
     reason: 'PUSH_NOTIFICATION_NOT_SUPPORTED',
     code: A2A_ERROR_CODE.PUSH_NOTIFICATION_NOT_SUPPORTED,
-    grpcStatus: GRPC_STATUS.FAILED_PRECONDITION,
+    grpcStatus: A2A_STATUS_CODE.FAILED_PRECONDITION,
     httpStatus: HTTP_STATUS.BAD_REQUEST,
     defaultMessage: 'Push Notification is not supported',
   },
   {
     name: 'UnsupportedOperationError',
     reason: 'UNSUPPORTED_OPERATION',
     code: A2A_ERROR_CODE.UNSUPPORTED_OPERATION,
-    grpcStatus: GRPC_STATUS.FAILED_PRECONDITION,
+    grpcStatus: A2A_STATUS_CODE.FAILED_PRECONDITION,
     httpStatus: HTTP_STATUS.BAD_REQUEST,
     defaultMessage: 'This operation is not supported',
   },
   {
     name: 'ContentTypeNotSupportedError',
     reason: 'CONTENT_TYPE_NOT_SUPPORTED',
     code: A2A_ERROR_CODE.CONTENT_TYPE_NOT_SUPPORTED,
-    grpcStatus: GRPC_STATUS.INVALID_ARGUMENT,
+    grpcStatus: A2A_STATUS_CODE.INVALID_ARGUMENT,
     httpStatus: HTTP_STATUS.BAD_REQUEST,
     defaultMessage: 'Incompatible content types',
   },
   {
     name: 'InvalidAgentResponseError',
     reason: 'INVALID_AGENT_RESPONSE',
     code: A2A_ERROR_CODE.INVALID_AGENT_RESPONSE,
-    grpcStatus: GRPC_STATUS.INTERNAL,
+    grpcStatus: A2A_STATUS_CODE.INTERNAL,
     httpStatus: HTTP_STATUS.INTERNAL_SERVER_ERROR,
     defaultMessage: 'Invalid agent response type',
   },
   {
     name: 'ExtendedAgentCardNotConfiguredError',
     reason: 'EXTENDED_AGENT_CARD_NOT_CONFIGURED',
     code: A2A_ERROR_CODE.EXTENDED_CARD_NOT_CONFIGURED,
-    grpcStatus: GRPC_STATUS.FAILED_PRECONDITION,
+    grpcStatus: A2A_STATUS_CODE.FAILED_PRECONDITION,
     httpStatus: HTTP_STATUS.BAD_REQUEST,
     defaultMessage: 'Extended Agent Card not configured',
   },
   {
     name: 'ExtensionSupportRequiredError',
     reason: 'EXTENSION_SUPPORT_REQUIRED',
     code: A2A_ERROR_CODE.EXTENSION_SUPPORT_REQUIRED,
-    grpcStatus: GRPC_STATUS.FAILED_PRECONDITION,
+    grpcStatus: A2A_STATUS_CODE.FAILED_PRECONDITION,
     httpStatus: HTTP_STATUS.BAD_REQUEST,
     defaultMessage: 'Extension support required',
   },
   {
     name: 'VersionNotSupportedError',
     reason: 'VERSION_NOT_SUPPORTED',
     code: A2A_ERROR_CODE.VERSION_NOT_SUPPORTED,
-    grpcStatus: GRPC_STATUS.FAILED_PRECONDITION,
+    grpcStatus: A2A_STATUS_CODE.FAILED_PRECONDITION,
     httpStatus: HTTP_STATUS.BAD_REQUEST,
     defaultMessage: 'Version not supported',
   },
   {
     name: 'RequestMalformedError',
     reason: 'INVALID_PARAMS',
     code: A2A_ERROR_CODE.INVALID_PARAMS,
-    grpcStatus: GRPC_STATUS.INVALID_ARGUMENT,
+    grpcStatus: A2A_STATUS_CODE.INVALID_ARGUMENT,
     httpStatus: HTTP_STATUS.BAD_REQUEST,
     defaultMessage: 'Request malformed',
   },
   {
     name: 'GenericError',
     reason: 'INTERNAL_ERROR',
     code: A2A_ERROR_CODE.INTERNAL_ERROR,
-    grpcStatus: GRPC_STATUS.INTERNAL,
+    grpcStatus: A2A_STATUS_CODE.INTERNAL,
     httpStatus: HTTP_STATUS.INTERNAL_SERVER_ERROR,
     defaultMessage: 'An unexpected error occurred.',
   },

src/errors/grpc.ts src/errors/grpc/index.tssrc/errors/grpc.ts renamed to src/errors/grpc/index.ts

@@ -13,14 +13,14 @@ import {
   A2A_ERROR_DOMAIN,
   A2A_ERROR_SPECS,
   A2A_ERROR_SPECS_BY_REASON,
+  A2A_STATUS_CODE,
   A2AError,
   type A2AErrorOptions,
   ERROR_INFO_TYPE,
-  GRPC_STATUS,
-} from './base.js';
-import { Any } from '../grpc/pb/google/protobuf/any.js';
-import { ErrorInfo } from '../grpc/pb/google/rpc/error_details.js';
-import { Status } from '../grpc/pb/google/rpc/status.js';
+} from '../base.js';
+import { Any } from '../../grpc/pb/google/protobuf/any.js';
+import { ErrorInfo } from '../../grpc/pb/google/rpc/error_details.js';
+import { Status } from '../../grpc/pb/google/rpc/status.js';
 
 /** Trailing metadata key for `google.rpc.Status`. */
 export const GRPC_STATUS_DETAILS_BIN = 'grpc-status-details-bin';
@@ -129,8 +129,8 @@ export const GRPC_ERROR_CLASSES: Readonly<
 export function grpcStatusFor(error: unknown): number {
   if (isGrpcError(error)) return error.status;
   if (error instanceof A2AError)
-    return A2A_ERROR_SPECS[error.name]?.grpcStatus ?? GRPC_STATUS.UNKNOWN;
-  return GRPC_STATUS.UNKNOWN;
+    return A2A_ERROR_SPECS[error.name]?.grpcStatus ?? A2A_STATUS_CODE.UNKNOWN;
+  return A2A_STATUS_CODE.UNKNOWN;
 }
 
 /** Encodes a `google.rpc.Status` + `ErrorInfo` blob for `grpc-status-details-bin`. */
@@ -229,9 +229,9 @@ export function fromGrpcError(error: grpc.ServiceError, method?: string): GrpcA2
   const suffix = method ? ` for ${method}` : '';
   return new GrpcGenericError({
     message:
-      `gRPC error${suffix}: ${error.code ?? GRPC_STATUS.UNKNOWN} ${error.details ?? ''}`.trim(),
+      `gRPC error${suffix}: ${error.code ?? A2A_STATUS_CODE.UNKNOWN} ${error.details ?? ''}`.trim(),
     cause: error,
-    status: error.code ?? GRPC_STATUS.UNKNOWN,
+    status: error.code ?? A2A_STATUS_CODE.UNKNOWN,
     statusDetailsBin,
   });
 }

src/errors/index.ts

@@ -1,6 +1,12 @@
-/** Barrel for the transport-agnostic A2A error hierarchy. */
+/**
+ * Transport-agnostic A2A error hierarchy: base class, semantic
+ * subclasses, plus the REST and JSON-RPC transport variants (both
+ * Workers-safe, no pb runtime dependency).
+ *
+ * gRPC errors live at `@a2a-js/sdk/errors/grpc` because their
+ * encode/decode helpers pull `@bufbuild/protobuf`.
+ */
 
 export * from './base.js';
 export * from './rest.js';
-export * from './grpc.js';
 export * from './json_rpc.js';

src/errors/rest.ts

@@ -15,7 +15,7 @@ import {
   type A2AErrorOptions,
   ERROR_INFO_TYPE,
   type ErrorDetail,
-  GRPC_STATUS_NAME,
+  A2A_STATUS_NAME,
   HTTP_STATUS,
   type RestErrorBody,
 } from './base.js';
@@ -150,7 +150,7 @@ export function toRestErrorBody(error: unknown, httpStatus: number): RestErrorBo
   if (error instanceof A2AError) {
     details.push(error.toErrorInfo());
     const spec = A2A_ERROR_SPECS[error.name];
-    statusName = spec ? (GRPC_STATUS_NAME[spec.grpcStatus] ?? 'UNKNOWN') : 'UNKNOWN';
+    statusName = spec ? (A2A_STATUS_NAME[spec.grpcStatus] ?? 'UNKNOWN') : 'UNKNOWN';
   } else if (httpStatus === HTTP_STATUS.NOT_FOUND) statusName = 'NOT_FOUND';
   else if (httpStatus === HTTP_STATUS.INTERNAL_SERVER_ERROR) statusName = 'INTERNAL';
   else if (httpStatus === HTTP_STATUS.BAD_REQUEST) statusName = 'INVALID_ARGUMENT';