refactor: define typed API for client call context (#232)

# Description

Provides typed API to read and update context to make predefined and
externally defined keys composable in the same way.

```ts
export type SystemParameters = Record<string, string>;

export const systemParametersKey = new ClientCallContextKey<SystemParameters>('systemParameters');

const myContext = ClientCallContext.create(
  systemParametersKey.set({ 'X-A2A-Extensions': 'http://example.com' })
);

const myParameters = systemParametersKey.get(myContext);
```

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

Author: ishymko

src/client/context.ts

@@ -0,0 +1,62 @@
+/**
+ * Opaque context object to carry per-call context data.
+ * Use {@link ClientCallContextKey} to create typed keys for storing and retrieving values.
+ */
+export type ClientCallContext = Record<symbol, unknown>;
+
+/**
+ * Function that applies an update to a {@link ClientCallContext}.
+ */
+export type ContextUpdate = (context: ClientCallContext) => void;
+
+export const ClientCallContext = {
+  /**
+   * Create a new {@link ClientCallContext} with optional updates applied.
+   */
+  create: (...updates: ContextUpdate[]): ClientCallContext => {
+    return ClientCallContext.createFrom(undefined, ...updates);
+  },
+
+  /**
+   * Create a new {@link ClientCallContext} based on an existing one with updates applied.
+   */
+  createFrom: (
+    context: ClientCallContext | undefined,
+    ...updates: ContextUpdate[]
+  ): ClientCallContext => {
+    const result = context ? { ...context } : {};
+    for (const update of updates) {
+      update(result);
+    }
+    return result;
+  },
+};
+
+/**
+ * Each instance represents a unique key for storing
+ * and retrieving typed values in a {@link ClientCallContext}.
+ *
+ * @example
+ * ```ts
+ * const key = new ClientCallContextKey<string>('My key');
+ * const context = ClientCallContext.create(key.set('example-value'));
+ * const value = key.get(context); // 'example-value'
+ * ```
+ */
+export class ClientCallContextKey<T> {
+  public readonly symbol: symbol;
+
+  constructor(description: string) {
+    this.symbol = Symbol(description);
+  }
+
+  set(value: T): ContextUpdate {
+    return (context) => {
+      context[this.symbol] = value;
+    };
+  }
+
+  get(context: ClientCallContext): T | undefined {
+    return context[this.symbol] as T | undefined;
+  }
+}

src/client/index.ts

@@ -25,3 +25,4 @@ export {
   ClientCallInput,
   ClientCallResult,
 } from './interceptors.js';
+export { ClientCallContext, ContextUpdate, ClientCallContextKey } from './context.js';

src/client/multitransport-client.ts

@@ -11,6 +11,7 @@ import {
   AgentCard,
 } from '../types.js';
 import { A2AStreamEventData, SendMessageResult } from './client.js';
+import { ClientCallContext } from './context.js';
 import {
   CallInterceptor,
   BeforeArgs,
@@ -55,7 +56,7 @@ export interface RequestOptions {
   /**
    * Arbitrary data available to interceptors and transport implementation.
    */
-  context?: Map<string, unknown>;
+  context?: ClientCallContext;
 }
 
 export class Client {

test/client/context.spec.ts

@@ -0,0 +1,28 @@
+import { expect } from 'chai';
+import { ClientCallContext, ClientCallContextKey } from '../../src/client/context.js';
+
+describe('ClientCallContext', () => {
+  const testKey = new ClientCallContextKey<string>('My key');
+
+  it('should create new context', () => {
+    const context = ClientCallContext.create(testKey.set('example-value'));
+    expect(testKey.get(context)).to.be.equal('example-value');
+  });
+
+  it('should create context from existing', () => {
+    const existingContext = ClientCallContext.createFrom(undefined, testKey.set('example-value'));
+    const context = ClientCallContext.createFrom(existingContext, testKey.set('new-value'));
+    expect(testKey.get(context)).to.be.equal('new-value');
+  });
+});
+
+describe('ClientCallContextKey', () => {
+  it('should be unique', () => {
+    const key1 = new ClientCallContextKey<string>('My key');
+    const key2 = new ClientCallContextKey<string>('My key');
+    expect(key1.symbol).to.not.equal(key2.symbol);
+    const context = ClientCallContext.create(key1.set('key1-value'), key2.set('key2-value'));
+    expect(key1.get(context)).to.be.equal('key1-value');
+    expect(key2.get(context)).to.be.equal('key2-value');
+  });
+});

test/client/multitransport-client.spec.ts

@@ -438,7 +438,7 @@ describe('Client', () => {
         interceptors: [
           {
             before: async (args) => {
-              args.options = { context: new Map([['foo', 'bar']]) };
+              args.options = { context: { [Symbol.for('foo')]: 'bar' } };
             },
             after: async () => {},
           },
@@ -456,8 +456,8 @@ describe('Client', () => {
 
       const result = await client.getTask(params);
 
-      expect(transport.getTask.calledOnceWith(params, { context: new Map([['foo', 'bar']]) })).to.be
-        .true;
+      expect(transport.getTask.calledOnceWith(params, { context: { [Symbol.for('foo')]: 'bar' } }))
+        .to.be.true;
       expect(result).to.equal(task);
     });