feat: Support multi-tenancy (#419)

# Description

Added support for multi-tenancy.

 ## Multi-Tenancy

This handler supports multi-tenant deployments through the `tenant`
field present
on all request objects (per A2A spec Sections 3.1.x and 4.4.6). The
tenant value
 flows through the system as follows:

1. **Transport layer** extracts tenant from the protocol-specific
source:
    - REST: URL path prefix (`/:tenant/...`)
    - JSON-RPC: `params.tenant` in the request body
    - gRPC: `tenant` field in the request message

2. **`ServerCallContext.tenant`** carries the tenant to all downstream
components,
    including `TaskStore`, `PushNotificationStore`, and `AgentExecutor`.

3. **`InMemoryTaskStore`** and **`InMemoryPushNotificationStore`** use
`context.tenant`
to scope data with composite keys (`{tenant}:{id}`), providing tenant
isolation.
 
Similar PR done in Python SDK:
a2aproject/a2a-python#758

Fixes #325 🦕

Author: bartek-gralewicz

.betterer.results

@@ -9,8 +9,8 @@ exports[`TypeScript Strict Mode`] = {
       [327, 15, 4, "tsc: Expected 2 arguments, but got 1.", "2087764327"],
       [350, 15, 4, "tsc: Expected 2 arguments, but got 1.", "2087764327"]
     ],
-    "src/server/transports/jsonrpc/jsonrpc_transport_handler.ts:1878858438": [
-      [89, 12, 10, "tsc: Variable \'rpcRequest\' is used before being assigned.", "3927050741"]
+    "src/server/transports/jsonrpc/jsonrpc_transport_handler.ts:3366537262": [
+      [90, 12, 10, "tsc: Variable \'rpcRequest\' is used before being assigned.", "3927050741"]
     ]
   }`
 };

src/client/factory.ts

@@ -4,6 +4,7 @@ import { AgentCardResolver } from './card-resolver.js';
 import { Client, ClientConfig } from './multitransport-client.js';
 import { JsonRpcTransportFactory } from './transports/json_rpc_transport.js';
 import { RestTransportFactory } from './transports/rest_transport.js';
+import { TenantTransportDecorator } from './transports/tenant_transport_decorator.js';
 import { TransportFactory } from './transports/transport.js';
 
 export interface ClientFactoryOptions {
@@ -95,29 +96,40 @@ export class ClientFactory {
 
   /**
    * Creates a new client from the provided agent card.
+   *
+   * When the selected `AgentInterface` declares a non-empty `tenant` value
+   * (per spec Section 4.4.6), the transport is automatically wrapped with a
+   * {@link TenantTransportDecorator} so the default tenant is applied to every
+   * request without requiring callers to set it manually.
    */
   async createFromAgentCard(agentCard: AgentCard): Promise<Client> {
     const interfaces = agentCard.supportedInterfaces ?? [];
-    const urlsPerAgentTransports = new CaseInsensitiveMap<string>();
-    for (const i of interfaces) {
-      const existing = urlsPerAgentTransports.get(i.protocolBinding);
-      if (!existing || i.protocolVersion === '1.0') {
-        urlsPerAgentTransports.set(i.protocolBinding, i.url);
+
+    const bestInterfacePerProtocol = new CaseInsensitiveMap<(typeof interfaces)[number]>();
+    for (const agentInterface of interfaces) {
+      const existing = bestInterfacePerProtocol.get(agentInterface.protocolBinding);
+      if (!existing || agentInterface.protocolVersion === '1.0') {
+        bestInterfacePerProtocol.set(agentInterface.protocolBinding, agentInterface);
       }
     }
+
     const transportsByPreference = [
       ...(this.options.preferredTransports ?? []),
       ...interfaces.map((i) => i.protocolBinding),
     ];
-    for (const transport of transportsByPreference) {
-      const url = urlsPerAgentTransports.get(transport);
-      const factory = this.transportsByName.get(transport);
-      if (factory && url) {
-        return new Client(
-          await factory.create(url, agentCard),
-          agentCard,
-          this.options.clientConfig
-        );
+    for (const transportName of transportsByPreference) {
+      const selectedInterface = bestInterfacePerProtocol.get(transportName);
+      const factory = this.transportsByName.get(transportName);
+      if (factory && selectedInterface) {
+        let transport = await factory.create(selectedInterface.url, agentCard);
+
+        // If the agent interface declares a default tenant, wrap the transport
+        // so the tenant is automatically applied to all requests.
+        if (selectedInterface.tenant) {
+          transport = new TenantTransportDecorator(transport, selectedInterface.tenant);
+        }
+
+        return new Client(transport, agentCard, this.options.clientConfig);
       }
     }
     throw new Error(

src/client/index.ts

@@ -10,6 +10,7 @@ export {
 } from './card-resolver.js';
 export { Client, type ClientConfig, type RequestOptions } from './multitransport-client.js';
 export type { Transport, TransportFactory } from './transports/transport.js';
+export { TenantTransportDecorator } from './transports/tenant_transport_decorator.js';
 export { ClientFactory, ClientFactoryOptions } from './factory.js';
 export { JsonRpcTransportFactory } from './transports/json_rpc_transport.js';
 export { RestTransportFactory } from './transports/rest_transport.js';

src/client/multitransport-client.ts

@@ -77,13 +77,17 @@ export class Client {
   /**
    * If the current agent card supports the extended feature, it will try to fetch the extended agent card from the server,
    * Otherwise it will return the current agent card value.
+   *
+   * When a default tenant is configured (via `TenantTransportDecorator`, wired
+   * automatically by `ClientFactory` from `AgentInterface.tenant`), the tenant
+   * is applied to the request transparently.
    */
   async getAgentCard(options?: RequestOptions): Promise<AgentCard> {
     if (this.agentCard.capabilities?.extendedAgentCard) {
       this.agentCard = await this.executeWithInterceptors(
         { method: 'getAgentCard' },
         options,
-        (_, options) => this.transport.getExtendedAgentCard(options)
+        (_, options) => this.transport.getExtendedAgentCard({ tenant: '' }, options)
       );
     }
     return this.agentCard;

src/client/transports/grpc/grpc_transport.ts

@@ -69,10 +69,13 @@ export class GrpcTransport implements Transport {
     return PROTOCOL_NAME;
   }
 
-  async getExtendedAgentCard(options?: RequestOptions): Promise<AgentCard> {
+  async getExtendedAgentCard(
+    params: GetExtendedAgentCardRequest,
+    options?: RequestOptions
+  ): Promise<AgentCard> {
     const rpcResponse = await this._sendGrpcRequest<GetExtendedAgentCardRequest, AgentCard>(
       'getExtendedAgentCard',
-      { tenant: '' },
+      params,
       options,
       this.grpcClient.getExtendedAgentCard.bind(this.grpcClient)
     );

src/client/transports/json_rpc_transport.ts

@@ -17,6 +17,7 @@ import { Transport, TransportFactory } from './transport.js';
 import {
   CancelTaskRequest,
   DeleteTaskPushNotificationConfigRequest,
+  GetExtendedAgentCardRequest,
   MessageFns,
   SendMessageRequest,
   SubscribeToTaskRequest,
@@ -51,12 +52,15 @@ export class JsonRpcTransport implements Transport {
     return PROTOCOL_NAME;
   }
 
-  async getExtendedAgentCard(options?: RequestOptions): Promise<AgentCard> {
-    const rpcResponse = await this._sendRpcRequest<undefined, AgentCard>(
+  async getExtendedAgentCard(
+    params: GetExtendedAgentCardRequest,
+    options?: RequestOptions
+  ): Promise<AgentCard> {
+    const rpcResponse = await this._sendRpcRequest<GetExtendedAgentCardRequest, AgentCard>(
       'GetExtendedAgentCard',
-      undefined,
+      params,
       options,
-      undefined
+      GetExtendedAgentCardRequest
     );
     return AgentCard.fromJSON(rpcResponse.result);
   }

src/client/transports/rest_transport.ts

@@ -20,6 +20,7 @@ import {
   AgentCard,
   CancelTaskRequest,
   DeleteTaskPushNotificationConfigRequest,
+  GetExtendedAgentCardRequest,
   GetTaskPushNotificationConfigRequest,
   GetTaskRequest,
   ListTaskPushNotificationConfigsRequest,
@@ -60,14 +61,22 @@ export class RestTransport implements Transport {
     this.customFetchImpl = options.fetchImpl;
   }
 
+  private _buildPath(path: string, tenant?: string): string {
+    return tenant ? '/' + encodeURIComponent(tenant) + path : path;
+  }
+
   get protocolName(): string {
     return PROTOCOL_NAME;
   }
 
-  async getExtendedAgentCard(options?: RequestOptions): Promise<AgentCard> {
+  async getExtendedAgentCard(
+    params: GetExtendedAgentCardRequest,
+    options?: RequestOptions
+  ): Promise<AgentCard> {
+    const path = this._buildPath('/extendedAgentCard', params.tenant);
     const response = await this._sendRequest<undefined, AgentCard>(
       'GET',
-      '/extendedAgentCard',
+      path,
       undefined,
       options,
       undefined,
@@ -81,9 +90,10 @@ export class RestTransport implements Transport {
     options?: RequestOptions
   ): Promise<SendMessageResult> {
     const requestBody = params;
+    const path = this._buildPath('/message:send', params.tenant);
     const response = await this._sendRequest<SendMessageRequest, SendMessageResponse>(
       'POST',
-      '/message:send',
+      path,
       requestBody,
       options,
       SendMessageRequest,
@@ -97,34 +107,38 @@ export class RestTransport implements Transport {
     options?: RequestOptions
   ): AsyncGenerator<StreamResponse, void, undefined> {
     const requestBody = SendMessageRequest.toJSON(params);
-    yield* this._sendStreamingRequest('/message:stream', requestBody, options);
+    const path = this._buildPath('/message:stream', params.tenant);
+    yield* this._sendStreamingRequest(path, requestBody, options);
   }
 
   async createTaskPushNotificationConfig(
     params: TaskPushNotificationConfig,
     options?: RequestOptions
   ): Promise<TaskPushNotificationConfig> {
-    const response = await this._sendRequest<
-      TaskPushNotificationConfig,
-      TaskPushNotificationConfig
-    >(
-      'POST',
+    const path = this._buildPath(
       `/tasks/${encodeURIComponent(params.taskId)}/pushNotificationConfigs`,
-      params,
-      options,
+      params.tenant
+    );
+    const response = await this._sendRequest<
       TaskPushNotificationConfig,
       TaskPushNotificationConfig
-    );
+    >('POST', path, params, options, TaskPushNotificationConfig, TaskPushNotificationConfig);
     return response;
   }
 
   async getTaskPushNotificationConfig(
     params: GetTaskPushNotificationConfigRequest,
     options?: RequestOptions
   ): Promise<TaskPushNotificationConfig> {
-    const response = await this._sendRequest<undefined, TaskPushNotificationConfig>(
+    const path = this._buildPath(
+      `/tasks/${encodeURIComponent(params.taskId)}/pushNotificationConfigs/${encodeURIComponent(
+        params.id
+      )}`,
+      params.tenant
+    );
+    const response = await this._sendRequest<void, TaskPushNotificationConfig>(
       'GET',
-      `/tasks/${params.taskId}/pushNotificationConfigs/${params.id}`,
+      path,
       undefined,
       options,
       undefined,
@@ -137,9 +151,13 @@ export class RestTransport implements Transport {
     params: ListTaskPushNotificationConfigsRequest,
     options?: RequestOptions
   ): Promise<ListTaskPushNotificationConfigsResponse> {
-    const response = await this._sendRequest<undefined, ListTaskPushNotificationConfigsResponse>(
+    const path = this._buildPath(
+      `/tasks/${encodeURIComponent(params.taskId)}/pushNotificationConfigs`,
+      params.tenant
+    );
+    const response = await this._sendRequest<void, ListTaskPushNotificationConfigsResponse>(
       'GET',
-      `/tasks/${params.taskId}/pushNotificationConfigs`,
+      path,
       undefined,
       options,
       undefined,
@@ -152,24 +170,26 @@ export class RestTransport implements Transport {
     params: DeleteTaskPushNotificationConfigRequest,
     options?: RequestOptions
   ): Promise<void> {
-    await this._sendRequest<undefined, void>(
-      'DELETE',
-      `/tasks/${params.taskId}/pushNotificationConfigs/${params.id}`,
-      undefined,
-      options,
-      undefined,
-      undefined
+    const path = this._buildPath(
+      `/tasks/${encodeURIComponent(params.taskId)}/pushNotificationConfigs/${encodeURIComponent(
+        params.id
+      )}`,
+      params.tenant
     );
+    await this._sendRequest<void, void>('DELETE', path, undefined, options, undefined, undefined);
   }
 
   async getTask(params: GetTaskRequest, options?: RequestOptions): Promise<Task> {
     const queryParams = new URLSearchParams();
     if (params.historyLength !== undefined) {
-      queryParams.set('historyLength', String(params.historyLength));
+      queryParams.set('historyLength', params.historyLength.toString());
     }
     const queryString = queryParams.toString();
-    const path = `/tasks/${params.id}${queryString ? `?${queryString}` : ''}`;
-    const response = await this._sendRequest<undefined, Task>(
+    const path = this._buildPath(
+      `/tasks/${encodeURIComponent(params.id)}${queryString ? `?${queryString}` : ''}`,
+      params.tenant
+    );
+    const response = await this._sendRequest<void, Task>(
       'GET',
       path,
       undefined,
@@ -181,9 +201,10 @@ export class RestTransport implements Transport {
   }
 
   async cancelTask(params: CancelTaskRequest, options?: RequestOptions): Promise<Task> {
-    const response = await this._sendRequest<undefined, Task>(
+    const path = this._buildPath(`/tasks/${encodeURIComponent(params.id)}:cancel`, params.tenant);
+    const response = await this._sendRequest<void, Task>(
       'POST',
-      `/tasks/${params.id}:cancel`,
+      path,
       undefined,
       options,
       undefined,
@@ -194,7 +215,6 @@ export class RestTransport implements Transport {
 
   async listTasks(params: ListTasksRequest, options?: RequestOptions): Promise<ListTasksResponse> {
     const queryParams = new URLSearchParams();
-    if (params.tenant) queryParams.set('tenant', params.tenant);
     if (params.contextId) queryParams.set('contextId', params.contextId);
     if (params.status !== undefined && params.status !== TaskState.TASK_STATE_UNSPECIFIED) {
       queryParams.set('status', taskStateToJSON(params.status));
@@ -209,9 +229,9 @@ export class RestTransport implements Transport {
       queryParams.set('includeArtifacts', String(params.includeArtifacts));
 
     const queryString = queryParams.toString();
-    const path = `/tasks${queryString ? `?${queryString}` : ''}`;
+    const path = this._buildPath(`/tasks${queryString ? `?${queryString}` : ''}`, params.tenant);
 
-    const response = await this._sendRequest<undefined, ListTasksResponse>(
+    const response = await this._sendRequest<void, ListTasksResponse>(
       'GET',
       path,
       undefined,
@@ -226,7 +246,11 @@ export class RestTransport implements Transport {
     params: SubscribeToTaskRequest,
     options?: RequestOptions
   ): AsyncGenerator<StreamResponse, void, undefined> {
-    yield* this._sendStreamingRequest(`/tasks/${params.id}:subscribe`, undefined, options);
+    const path = this._buildPath(
+      `/tasks/${encodeURIComponent(params.id)}:subscribe`,
+      params.tenant
+    );
+    yield* this._sendStreamingRequest(path, undefined, options);
   }
 
   private _fetch(...args: Parameters<typeof fetch>): ReturnType<typeof fetch> {