fix(compat/v0_3): call context builder for compatibility layer (#604)

# Description

The v0.3 compat REST router and gRPC service hard-coded `new
ServerCallContext(...)` and never invoked an operator-supplied
`contextBuilder`. State that `contextBuilder` would inject (tenant,
auth, request-id) was silently missing on v0.3 REST and gRPC requests.

JSON-RPC was already correct: the v1.0 `jsonRpcHandler` builds the
context once and then dispatches to either the v1.0 or v0.3 transport
handler based on the JSON-RPC method name, so an injected
`contextBuilder` reached v0.3 traffic on that path. This change brings
REST and gRPC to parity.

- Add `contextBuilder?: ServerCallContextBuilder` to
`LegacyRestHandlerOptions` and `LegacyGrpcServiceOptions`.
- Route both compat handlers through `options.contextBuilder ??
defaultServerCallContextBuilder`.
- Pass `headers` through in both paths so the default builder's
`context.state[STATE_HEADERS_KEY]` behavior isn't silently lost on v0.3
requests.
- Fix `LegacyGrpcServiceOptions` docstring that falsely claimed "Same
shape as v1.0 `GrpcServiceOptions`".

The v1.0 Express `restHandler` auto-forwards its `contextBuilder` into
the compat sub-router via structural typing (no v1.0-side change).
gRPC operators pass the same builder to `legacyGrpcService` next to
`grpcService`.

Fixes #600

Author: JakubWorek

docs/compatibility-v0_3.md

@@ -6,14 +6,14 @@ This directory (`src/compat/v0_3/`) provides the foundational data representatio
 
 The compat layer is shipped as six subpath exports off `@a2a-js/sdk`. Each subpath carries only the peer dependencies (`express`, `@grpc/grpc-js`) its runtime needs, so a Workers consumer that only opts into the compat-aware client transports never has to pull in Node-only modules.
 
-| Subpath                                  | What it exports                                                                                                                                                                                                                                                                                                                                                                         | Peer deps           |
-| :--------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------ |
-| `@a2a-js/sdk/compat/v0_3`                | v0.3 protocol constants (`A2A_LEGACY_PROTOCOL_VERSION`, `LEGACY_HTTP_EXTENSION_HEADER`, `LEGACY_JSON_CONTENT_TYPE`, the `LEGACY_METHOD_*` literals) and method-name translators (`legacyJsonRpcToV1Method`, `v1MethodToLegacyJsonRpc`, `legacyJsonRpcToLegacyGrpcMethod`, `legacyGrpcToLegacyJsonRpcMethod`, `legacyGrpcToV1Method`, `v1MethodToLegacyGrpc`, `isLegacyJsonRpcMethod`, `isV1JsonRpcMethod`).  | none (Workers-safe) |
-| `@a2a-js/sdk/compat/v0_3/server`         | Framework-agnostic transport handlers (`LegacyJsonRpcTransportHandler`, `LegacyRestTransportHandler`, `toLegacyHTTPError`), push-notification factory (`createLegacyAwarePushNotificationSender`) and serializer (`V03PushNotificationSerializer`), and the `LegacyA2AError` class. Mount the transport handlers from any HTTP runtime (Express, Fastify, Hono, Cloudflare Workers, …). | none (Workers-safe) |
-| `@a2a-js/sdk/compat/v0_3/server/express` | Express routers (`legacyAgentCardRouter`, `legacyRestRouter`) that wrap the handlers above with the v0.3 well-known agent-card and REST endpoint paths. Header-based dispatch on `A2A-Version`.                                                                                                                                                                                         | `express`           |
-| `@a2a-js/sdk/compat/v0_3/server/grpc`    | v0.3 gRPC service factory (`legacyGrpcService`), service descriptor (`LegacyA2AService`), and options type. Register alongside the v1.0 `grpcService` on the same gRPC `Server`.                                                                                                                                                                                                        | `@grpc/grpc-js`     |
-| `@a2a-js/sdk/compat/v0_3/client`         | Card-resolver helpers (`isLegacyAgentCard`, `parseLegacyAgentCard`) and the v0.3 JSON-RPC + REST client transports (`LegacyJsonRpcTransport`, `LegacyRestTransport`).                                                                                                                                                                                                                   | none (Workers-safe) |
-| `@a2a-js/sdk/compat/v0_3/client/grpc`    | v0.3 gRPC client transport (`LegacyGrpcTransport`), instantiated by the v1.0 `GrpcTransportFactory` when `legacyCompat: { enabled: true }` and the matched `AgentInterface.protocolVersion` falls in `[0.3, 1.0)`.                                                                                                                                                                      | `@grpc/grpc-js`     |
+| Subpath                                  | What it exports                                                                                                                                                                                                                                                                                                                                                                                             | Peer deps           |
+| :--------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------ |
+| `@a2a-js/sdk/compat/v0_3`                | v0.3 protocol constants (`A2A_LEGACY_PROTOCOL_VERSION`, `LEGACY_HTTP_EXTENSION_HEADER`, `LEGACY_JSON_CONTENT_TYPE`, the `LEGACY_METHOD_*` literals) and method-name translators (`legacyJsonRpcToV1Method`, `v1MethodToLegacyJsonRpc`, `legacyJsonRpcToLegacyGrpcMethod`, `legacyGrpcToLegacyJsonRpcMethod`, `legacyGrpcToV1Method`, `v1MethodToLegacyGrpc`, `isLegacyJsonRpcMethod`, `isV1JsonRpcMethod`). | none (Workers-safe) |
+| `@a2a-js/sdk/compat/v0_3/server`         | Framework-agnostic transport handlers (`LegacyJsonRpcTransportHandler`, `LegacyRestTransportHandler`, `toLegacyHTTPError`), push-notification factory (`createLegacyAwarePushNotificationSender`) and serializer (`V03PushNotificationSerializer`), and the `LegacyA2AError` class. Mount the transport handlers from any HTTP runtime (Express, Fastify, Hono, Cloudflare Workers, …).                     | none (Workers-safe) |
+| `@a2a-js/sdk/compat/v0_3/server/express` | Express routers (`legacyAgentCardRouter`, `legacyRestRouter`) that wrap the handlers above with the v0.3 well-known agent-card and REST endpoint paths. Header-based dispatch on `A2A-Version`.                                                                                                                                                                                                             | `express`           |
+| `@a2a-js/sdk/compat/v0_3/server/grpc`    | v0.3 gRPC service factory (`legacyGrpcService`), service descriptor (`LegacyA2AService`), and options type. Register alongside the v1.0 `grpcService` on the same gRPC `Server`.                                                                                                                                                                                                                            | `@grpc/grpc-js`     |
+| `@a2a-js/sdk/compat/v0_3/client`         | Card-resolver helpers (`isLegacyAgentCard`, `parseLegacyAgentCard`) and the v0.3 JSON-RPC + REST client transports (`LegacyJsonRpcTransport`, `LegacyRestTransport`).                                                                                                                                                                                                                                       | none (Workers-safe) |
+| `@a2a-js/sdk/compat/v0_3/client/grpc`    | v0.3 gRPC client transport (`LegacyGrpcTransport`), instantiated by the v1.0 `GrpcTransportFactory` when `legacyCompat: { enabled: true }` and the matched `AgentInterface.protocolVersion` falls in `[0.3, 1.0)`.                                                                                                                                                                                          | `@grpc/grpc-js`     |
 
 The bidirectional v0.3 ↔ v1.0 payload translators in `./translate/` are intentionally NOT part of the public surface and may change without a major-version bump.
 
@@ -67,6 +67,8 @@ Operators advertise a binding at v0.3 by declaring a per-interface `protocolVers
 
 The v1.0 gRPC service factory (`src/server/grpc/grpc_service.ts`) intentionally does **not** carry a `legacyCompat` option; v0.3 gRPC clients are served by importing `legacyGrpcService` from `@a2a-js/sdk/compat/v0_3/server/grpc` and registering it alongside the v1.0 `grpcService` on the same `Server`. (The v1.0 `@a2a-js/sdk/server/grpc` barrel does not re-export `legacyGrpcService`; the explicit compat import keeps `@grpc/grpc-js` out of the v1.0 dependency graph for operators who only deploy the v1.0 service.)
 
+Executor-facing hooks (`userBuilder`, `contextBuilder`) are wire-version-agnostic by design. The Express `restHandler` and `jsonRpcHandler` forward these hooks into their compat sub-routers automatically; `legacyGrpcService` accepts the same options as `grpcService` so operators can pass the same builder to both `Server.addService` calls. Every code path — v1.0 and v0.3 — invokes `options.contextBuilder ?? defaultServerCallContextBuilder` before dispatching to the `A2ARequestHandler`.
+
 ### JSON-RPC method dispatch
 
 `jsonRpcHandler({ legacyCompat: { enabled: true } })` routes each request body based on its `method` field:

src/compat/v0_3/README.md

@@ -14,7 +14,11 @@ import express, {
 
 import { A2A_VERSION_HEADER, HTTP_EXTENSION_HEADER } from '../../../../constants.js';
 import { Extensions } from '../../../../extensions.js';
-import { ServerCallContext } from '../../../../server/context.js';
+import {
+  ServerCallContext,
+  ServerCallContextBuilder,
+  defaultServerCallContextBuilder,
+} from '../../../../server/context.js';
 import { UserBuilder, delegateAsyncIterator } from '../../../../server/express/common.js';
 import { type A2ARequestHandler } from '../../../../server/request_handler/a2a_request_handler.js';
 import { SSE_HEADERS, formatSSEEvent, formatSSEErrorEvent } from '../../../../sse_utils.js';
@@ -49,6 +53,14 @@ import {
 export interface LegacyRestHandlerOptions {
   requestHandler: A2ARequestHandler;
   userBuilder: UserBuilder;
+  /**
+   * Custom builder for the per-request {@link ServerCallContext}. When
+   * omitted, {@link defaultServerCallContextBuilder} is used, which
+   * populates `context.state[STATE_HEADERS_KEY]` with the raw request
+   * headers. Auto-forwarded from the v1.0 `restHandler` options when
+   * this router is mounted via `legacyCompat: { enabled: true }`.
+   */
+  contextBuilder?: ServerCallContextBuilder;
 }
 
 /** Converts JSON parse errors from `express.json()` to v0.3-shaped 400 responses. */
@@ -118,11 +130,13 @@ export function legacyRestRouter(options: LegacyRestHandlerOptions): RequestHand
   const buildContext = async (req: Request): Promise<ServerCallContext> => {
     const user = await options.userBuilder(req);
     const requestedVersion = req.header(A2A_VERSION_HEADER) || A2A_LEGACY_PROTOCOL_VERSION;
-    const context = new ServerCallContext({
-      requestedExtensions: Extensions.parseServiceParameter(
+    const ctxBuilder = options.contextBuilder ?? defaultServerCallContextBuilder;
+    const context = ctxBuilder({
+      extensions: Extensions.parseServiceParameter(
         req.header(LEGACY_HTTP_EXTENSION_HEADER) ?? req.header(HTTP_EXTENSION_HEADER)
       ),
       user,
+      headers: req.headers,
       requestedVersion,
       tenant: (req.params.tenant as string) || undefined,
     });

src/compat/v0_3/server/express/rest_handler.ts

@@ -33,7 +33,11 @@ import {
 } from '../../grpc/pb/a2a.js';
 import { Empty } from '../../grpc/pb/google/protobuf/empty.js';
 import { A2ARequestHandler } from '../../../../server/request_handler/a2a_request_handler.js';
-import { ServerCallContext } from '../../../../server/context.js';
+import {
+  ServerCallContext,
+  ServerCallContextBuilder,
+  defaultServerCallContextBuilder,
+} from '../../../../server/context.js';
 import { Extensions } from '../../../../extensions.js';
 import { UserBuilder } from './common.js';
 import { A2A_VERSION_HEADER, HTTP_EXTENSION_HEADER } from '../../../../constants.js';
@@ -78,10 +82,18 @@ import type {
   TaskPushNotificationConfig as V1TaskPushNotificationConfig,
 } from '../../../../types/pb/a2a.js';
 
-/** Same shape as v1.0 `GrpcServiceOptions`. */
+/** Options for the legacy v0.3 gRPC service handler. */
 export interface LegacyGrpcServiceOptions {
   requestHandler: A2ARequestHandler;
   userBuilder: UserBuilder;
+  /**
+   * Custom builder for the per-request {@link ServerCallContext}. When
+   * omitted, {@link defaultServerCallContextBuilder} is used, which
+   * populates `context.state[STATE_HEADERS_KEY]` with the raw request
+   * metadata. Provide the same builder passed to the v1.0 `grpcService`
+   * so v0.3 traffic sees the same context shape.
+   */
+  contextBuilder?: ServerCallContextBuilder;
 }
 
 /**
@@ -107,7 +119,12 @@ export function legacyGrpcService(options: LegacyGrpcServiceOptions): A2AService
     converter: (res: TCoreRes) => TPbRes
   ): Promise<void> => {
     try {
-      const context = await _buildContext(call, options.userBuilder, requestHandler);
+      const context = await _buildContext(
+        call,
+        options.userBuilder,
+        requestHandler,
+        options.contextBuilder
+      );
       const coreRequest = parser(call.request);
       const result = await handler(coreRequest, context);
       call.sendMetadata(buildMetadata(context));
@@ -126,7 +143,12 @@ export function legacyGrpcService(options: LegacyGrpcServiceOptions): A2AService
     converter: (res: TCoreRes) => TPbRes
   ): Promise<void> => {
     try {
-      const context = await _buildContext(call, options.userBuilder, requestHandler);
+      const context = await _buildContext(
+        call,
+        options.userBuilder,
+        requestHandler,
+        options.contextBuilder
+      );
       const coreRequest = parser(call.request);
       const stream = handler(coreRequest, context);
       call.sendMetadata(buildMetadata(context));
@@ -461,7 +483,8 @@ const mapToError = (error: unknown): Partial<grpc.ServiceError> => {
 const _buildContext = async (
   call: grpc.ServerUnaryCall<unknown, unknown> | grpc.ServerWritableStream<unknown, unknown>,
   userBuilder: UserBuilder,
-  requestHandler: A2ARequestHandler
+  requestHandler: A2ARequestHandler,
+  contextBuilder?: ServerCallContextBuilder
 ): Promise<ServerCallContext> => {
   const user = await userBuilder(call);
   // Accept both v0.3's `X-A2A-Extensions` and v1.0's `A2A-Extensions`.
@@ -475,9 +498,17 @@ const _buildContext = async (
   const versionHeaders = call.metadata.get(A2A_VERSION_HEADER.toLowerCase());
   const requestedVersion = versionHeaders.length > 0 ? versionHeaders[0].toString() : undefined;
 
-  const context = new ServerCallContext({
-    requestedExtensions: Extensions.parseServiceParameter(extensionString),
+  // Convert gRPC metadata to the transport-agnostic RequestHeaders shape.
+  const headers: Record<string, string | string[] | undefined> = {};
+  for (const [key, value] of Object.entries(call.metadata.getMap())) {
+    headers[key] = value.toString();
+  }
+
+  const ctxBuilder = contextBuilder ?? defaultServerCallContextBuilder;
+  const context = ctxBuilder({
+    extensions: Extensions.parseServiceParameter(extensionString),
     user,
+    headers,
     requestedVersion,
   });
 

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

@@ -16,6 +16,11 @@ import {
   type Task as V1Task,
 } from '../../../../../src/types/pb/a2a.js';
 import { decodeErrorInfo, decodeStatus } from '../../../../../src/errors/grpc/index.js';
+import {
+  STATE_HEADERS_KEY,
+  ServerCallContextBuilder,
+  defaultServerCallContextBuilder,
+} from '../../../../../src/server/context.js';
 
 // v0.3 GRPC interface so validateVersion accepts the defaulted '0.3'.
 const testAgentCard: V1AgentCard = {
@@ -508,6 +513,89 @@ describe('legacyGrpcService', () => {
     });
   });
 
+  describe('context builder', () => {
+    // Regression test: a custom `contextBuilder` set on the
+    // v0.3 compat gRPC service used to be silently dropped; the service
+    // hard-coded `new ServerCallContext(...)` and ignored operator hooks.
+
+    it('invokes the operator-supplied contextBuilder on each call', async () => {
+      const contextBuilder = vi.fn(defaultServerCallContextBuilder);
+      const svc = legacyGrpcService({
+        requestHandler: mockRequestHandler,
+        userBuilder: async () => ({ id: 'test-user' }) as any,
+        contextBuilder,
+      });
+      (mockRequestHandler.getTask as Mock).mockResolvedValue(v1Task('t-1'));
+
+      const call = createMockUnaryCall({ name: 'tasks/t-1', historyLength: 0 });
+      const callback = vi.fn();
+      await svc.getTask(call, callback);
+
+      expect(contextBuilder).toHaveBeenCalledTimes(1);
+      const opts = contextBuilder.mock.calls[0]![0];
+      expect(opts.requestedVersion).to.equal('0.3');
+      // Metadata (converted to the transport-agnostic RequestHeaders
+      // shape) must be forwarded so the operator can key off it and
+      // so the default builder's header-stashing keeps working.
+      assert.isDefined(opts.headers);
+      expect(opts.headers[A2A_VERSION_HEADER.toLowerCase()]).to.equal('0.3');
+    });
+
+    it('lets a custom contextBuilder inject tenant into context.state', async () => {
+      // Mirrors the reporter's use case: pull a tenant identifier off
+      // a metadata header and stash it in `state` so the TaskStore /
+      // PushNotificationStore downstream can read it.
+      const tenantBuilder: ServerCallContextBuilder = (opts) => {
+        const ctx = defaultServerCallContextBuilder(opts);
+        const tenantHeader = opts.headers['x-tenant-id'];
+        ctx.state.set('tenantId', typeof tenantHeader === 'string' ? tenantHeader : undefined);
+        return ctx;
+      };
+      const svc = legacyGrpcService({
+        requestHandler: mockRequestHandler,
+        userBuilder: async () => ({ id: 'test-user' }) as any,
+        contextBuilder: tenantBuilder,
+      });
+      let observedTenant: unknown;
+      (mockRequestHandler.getTask as Mock).mockImplementation(async (_req, ctx) => {
+        observedTenant = ctx.state.get('tenantId');
+        return v1Task('t-tenant');
+      });
+
+      const call = createMockUnaryCall(
+        { name: 'tasks/t-tenant', historyLength: 0 },
+        { 'x-tenant-id': 'acme' }
+      );
+      const callback = vi.fn();
+      await svc.getTask(call, callback);
+
+      expect(observedTenant).to.equal('acme');
+    });
+
+    it('falls back to the default builder when contextBuilder is omitted', async () => {
+      // Without a custom builder, `defaultServerCallContextBuilder`
+      // must still run — this pre-populates `context.state[STATE_HEADERS_KEY]`
+      // with the raw metadata, mirroring the v1.0 gRPC path exactly.
+      let observedHeaders: unknown;
+      (mockRequestHandler.getTask as Mock).mockImplementation(async (_req, ctx) => {
+        observedHeaders = ctx.state.get(STATE_HEADERS_KEY);
+        return v1Task('t-default');
+      });
+
+      const call = createMockUnaryCall(
+        { name: 'tasks/t-default', historyLength: 0 },
+        { 'x-custom': 'v' }
+      );
+      const callback = vi.fn();
+      await handler.getTask(call, callback);
+
+      assert.isDefined(observedHeaders);
+      const headers = observedHeaders as Record<string, string>;
+      expect(headers[A2A_VERSION_HEADER.toLowerCase()]).to.equal('0.3');
+      expect(headers['x-custom']).to.equal('v');
+    });
+  });
+
   describe('version validation', () => {
     it('rejects requests for a v1.0 version when the agent only declares v0.3 gRPC', async () => {
       const call = createMockUnaryCall(