feat(server): expose SendMessageRequest metadata to AgentExecutor via RequestContext (#564)

Adds an optional readonly `metadata: Record<string, unknown>` property
to
`RequestContext`, populated from `SendMessageRequest.metadata` in both
`sendMessage` and `sendMessageStream`.

- The property is appended as a trailing optional constructor parameter,
so
  existing `RequestContext` construction sites are unaffected.
- It is `undefined` when the request carries no metadata — no behavior
change
  for existing executors.
- Two tests added to `default_request_handler.spec.ts`: request metadata
reaches the executor on both the unary and streaming send paths
(exercised
with the spec's own `a2a-service-parameters` pattern), and the property
  stays `undefined` when the request carries none.

# Description

Thank you for opening a Pull Request!
Before submitting your PR, there are a few things you can do to make
sure it goes smoothly:

- [x] Follow the [`CONTRIBUTING`
Guide](https://github.com/google-a2a/a2a-js/blob/main/CONTRIBUTING.md).
- [x] Make your Pull Request title in the
<https://www.conventionalcommits.org/> specification.
- Important Prefixes for
[release-please](https://github.com/googleapis/release-please):
- `fix:` which represents bug fixes, and correlates to a
[SemVer](https://semver.org/) patch.
- `feat:` represents a new feature, and correlates to a SemVer minor.
- `feat!:`, or `fix!:`, `refactor!:`, etc., which represent a breaking
change (indicated by the `!`) and will result in a SemVer major.
- [x] Ensure the tests and linter pass
- [x] Appropriate docs were updated (if necessary)

Fixes #563 🦕

Author: boblangley

src/server/agent_execution/request_context.ts

@@ -8,20 +8,29 @@ export class RequestContext {
   public readonly task?: Task;
   public readonly referenceTasks?: Task[];
   public readonly context: ServerCallContext;
+  /**
+   * The request-level metadata from the originating `SendMessageRequest`,
+   * when provided. This is the spec's "flexible key-value map for passing
+   * additional context or parameters" and is distinct from
+   * `userMessage.metadata`.
+   */
+  public readonly metadata?: Record<string, unknown>;
 
   constructor(
     userMessage: Message,
     taskId: string,
     contextId: string,
     context: ServerCallContext,
     task?: Task,
-    referenceTasks?: Task[]
+    referenceTasks?: Task[],
+    metadata?: Record<string, unknown>
   ) {
     this.userMessage = userMessage;
     this.taskId = taskId;
     this.contextId = contextId;
     this.context = context;
     this.task = task;
     this.referenceTasks = referenceTasks;
+    this.metadata = metadata ? structuredClone(metadata) : undefined;
   }
 }

src/server/request_handler/default_request_handler.ts

@@ -143,7 +143,8 @@ export class DefaultRequestHandler implements A2ARequestHandler {
 
   private async _createRequestContext(
     incomingMessage: Message,
-    context: ServerCallContext
+    context: ServerCallContext,
+    requestMetadata?: Record<string, unknown>
   ): Promise<RequestContext> {
     let task: Task | undefined;
     let referenceTasks: Task[] | undefined;
@@ -220,7 +221,15 @@ export class DefaultRequestHandler implements A2ARequestHandler {
       contextId,
       taskId,
     };
-    return new RequestContext(messageForContext, taskId, contextId, context, task, referenceTasks);
+    return new RequestContext(
+      messageForContext,
+      taskId,
+      contextId,
+      context,
+      task,
+      referenceTasks,
+      requestMetadata
+    );
   }
 
   private async _processEvents(
@@ -558,7 +567,11 @@ export class DefaultRequestHandler implements A2ARequestHandler {
     const resultManager = new ResultManager(this.taskStore, context);
     resultManager.setContext(incomingMessage);
 
-    const requestContext = await this._createRequestContext(incomingMessage, context);
+    const requestContext = await this._createRequestContext(
+      incomingMessage,
+      context,
+      params.metadata
+    );
     const taskId = requestContext.taskId;
     const finalMessageForAgent = requestContext.userMessage;
 
@@ -652,7 +665,11 @@ export class DefaultRequestHandler implements A2ARequestHandler {
     const resultManager = new ResultManager(this.taskStore, context);
     resultManager.setContext(incomingMessage);
 
-    const requestContext = await this._createRequestContext(incomingMessage, context);
+    const requestContext = await this._createRequestContext(
+      incomingMessage,
+      context,
+      params.metadata
+    );
     const taskId = requestContext.taskId;
 
     const eventBus = this.eventBusManager.createOrGetByTaskId(taskId);

test/server/default_request_handler.spec.ts

@@ -3543,6 +3543,130 @@ describe('DefaultRequestHandler as A2ARequestHandler', () => {
     expect(capturedRequestContext?.context?.user).to.be.an.instanceOf(UnauthenticatedUser);
   });
 
+  it('should expose SendMessageRequest metadata to agentExecutor via RequestContext', async () => {
+    const requestMetadata = {
+      'a2a-service-parameters': { 'A2A-Extensions': 'https://example.com/extensions/sample/v1' },
+      traceId: 'trace-123',
+    };
+
+    const params: SendMessageRequest = {
+      tenant: '',
+      metadata: requestMetadata,
+      configuration: undefined,
+      message: {
+        messageId: 'msg-request-metadata',
+        role: Role.ROLE_USER,
+        parts: [
+          {
+            content: { $case: 'text', value: 'Verify request metadata.' },
+            filename: '',
+            mediaType: 'text/plain',
+            metadata: undefined,
+          },
+        ],
+        contextId: 'metadata-context-id',
+        taskId: '',
+        extensions: [],
+        referenceTaskIds: [],
+        metadata: {},
+      },
+    };
+
+    let capturedRequestContext: RequestContext | undefined;
+    (mockAgentExecutor.execute as unknown as Mock).mockImplementation(
+      async (ctx: RequestContext, bus: ExecutionEventBus) => {
+        capturedRequestContext = ctx;
+        bus.publish(
+          AgentEvent.task({
+            id: ctx.taskId,
+            contextId: ctx.contextId,
+            status: {
+              state: TaskState.TASK_STATE_COMPLETED,
+              message: undefined,
+              timestamp: undefined,
+            },
+            artifacts: [],
+            history: [],
+            metadata: {},
+          })
+        );
+        bus.finished();
+      }
+    );
+
+    await handler.sendMessage(params, serverCallContext);
+    expect(capturedRequestContext?.metadata).to.deep.equal(
+      requestMetadata,
+      'sendMessage should thread request metadata into RequestContext'
+    );
+
+    capturedRequestContext = undefined;
+    const streamParams: SendMessageRequest = {
+      ...params,
+      message: { ...params.message!, messageId: 'msg-request-metadata-stream' },
+    };
+    for await (const event of handler.sendMessageStream(streamParams, serverCallContext)) {
+      void event; // drain the stream
+    }
+    expect(capturedRequestContext?.metadata).to.deep.equal(
+      requestMetadata,
+      'sendMessageStream should thread request metadata into RequestContext'
+    );
+  });
+
+  it('should leave RequestContext metadata undefined when the request carries none', async () => {
+    const params: SendMessageRequest = {
+      tenant: '',
+      metadata: undefined,
+      configuration: undefined,
+      message: {
+        messageId: 'msg-no-request-metadata',
+        role: Role.ROLE_USER,
+        parts: [
+          {
+            content: { $case: 'text', value: 'No request metadata.' },
+            filename: '',
+            mediaType: 'text/plain',
+            metadata: undefined,
+          },
+        ],
+        contextId: 'no-metadata-context-id',
+        taskId: '',
+        extensions: [],
+        referenceTaskIds: [],
+        metadata: {},
+      },
+    };
+
+    let capturedRequestContext: RequestContext | undefined;
+    (mockAgentExecutor.execute as unknown as Mock).mockImplementation(
+      async (ctx: RequestContext, bus: ExecutionEventBus) => {
+        capturedRequestContext = ctx;
+        bus.publish(
+          AgentEvent.task({
+            id: ctx.taskId,
+            contextId: ctx.contextId,
+            status: {
+              state: TaskState.TASK_STATE_COMPLETED,
+              message: undefined,
+              timestamp: undefined,
+            },
+            artifacts: [],
+            history: [],
+            metadata: {},
+          })
+        );
+        bus.finished();
+      }
+    );
+
+    await handler.sendMessage(params, serverCallContext);
+    expect(capturedRequestContext?.metadata).to.equal(
+      undefined,
+      'RequestContext metadata should be undefined when the request has none'
+    );
+  });
+
   describe('getAuthenticatedExtendedAgentCard tests', async () => {
     class A2AUser implements User {
       constructor(private _isAuthenticated: boolean) {}