@mailmodo/a2a 0.3.3 → 0.3.7

package/README.md

@@ -1,4 +1,4 @@
-# A2A JavaScript SDK
+# A2A JavaScript SDK - Mailmodo Edition
 
 [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 
@@ -13,25 +13,62 @@
 
 <!-- markdownlint-enable no-inline-html -->
 
+> **Note**: This is Mailmodo's customized fork of the [official A2A JavaScript SDK](https://github.com/a2aproject/a2a-js). Key differences:
+> - **Dual Module Support**: Supports both **CommonJS** and **ESM** (upstream only supports ESM)
+> - **Backwards Compatibility**: Works with older TypeScript configurations using `typesVersions`
+
 ## Installation
 
-You can install the A2A SDK using `npm`.
+You can install the Mailmodo A2A SDK using `npm`.
 
 ```bash
-npm install @a2a-js/sdk
+npm install @mailmodo/a2a
 ```
 
 ### For Server Usage
 
-If you plan to use the A2A server functionality (`A2AExpressApp`), you'll also need to install Express as it's a peer dependency:
+If you plan to use the Express integration (imports from `@mailmodo/a2a/server/express`) for A2A server, you'll also need to install Express as it's a peer dependency:
 
 ```bash
 npm install express
 ```
 
-You can also find JavaScript samples [here](https://github.com/google-a2a/a2a-samples/tree/main/samples/js).
+You can also find some samples [here](https://github.com/mailmodo/a2a-js/tree/main/src/samples).
+
+---
+
+## Module System Compatibility
+
+This package supports both **CommonJS** and **ESM** module systems:
+
+### CommonJS (Node.js)
+```javascript
+const { Task, Message } = require('@mailmodo/a2a');
+const { DefaultRequestHandler } = require('@mailmodo/a2a/server');
+const { A2AExpressApp } = require('@mailmodo/a2a/server/express');
+const { ClientFactory } = require('@mailmodo/a2a/client');
+```
+
+### ESM (ES Modules)
+```javascript
+import { Task, Message } from '@mailmodo/a2a';
+import { DefaultRequestHandler } from '@mailmodo/a2a/server';
+import { A2AExpressApp } from '@mailmodo/a2a/server/express';
+import { ClientFactory } from '@mailmodo/a2a/client';
+```
+
+
+---
+
+## Compatibility
 
------
+This SDK implements the A2A Protocol Specification [`v0.3.0`](https://a2a-protocol.org/v0.3.0/specification).
+
+| Transport | Client | Server |
+| :--- | :---: | :---: |
+| **JSON-RPC** | ✅ | ✅ |
+| **HTTP+JSON/REST** | ✅ | ✅ |
+| **gRPC** | ❌ | ❌ |
 
 ## Quickstart
 
@@ -43,41 +80,46 @@ The core of an A2A server is the `AgentExecutor`, which contains your agent's lo
 
 ```typescript
 // server.ts
-import express from "express";
-import { v4 as uuidv4 } from "uuid";
-import type { AgentCard, Message } from "@a2a-js/sdk";
+import express from 'express';
+import { v4 as uuidv4 } from 'uuid';
+import { AgentCard, Message, AGENT_CARD_PATH } from '@mailmodo/a2a';
 import {
   AgentExecutor,
   RequestContext,
   ExecutionEventBus,
   DefaultRequestHandler,
   InMemoryTaskStore,
-} from "@a2a-js/sdk/server";
-import { A2AExpressApp } from "@a2a-js/sdk/server/express";
+} from '@mailmodo/a2a/server';
+import { agentCardHandler, jsonRpcHandler, restHandler, UserBuilder } from '@mailmodo/a2a/server/express';
 
 // 1. Define your agent's identity card.
 const helloAgentCard: AgentCard = {
-  name: "Hello Agent",
-  description: "A simple agent that says hello.",
-  protocolVersion: "0.3.0",
-  version: "0.1.0",
-  url: "http://localhost:4000/", // The public URL of your agent server
-  skills: [ { id: "chat", name: "Chat", description: "Say hello", tags: ["chat"] } ],
-  // --- Other AgentCard fields omitted for brevity ---
+  name: 'Hello Agent',
+  description: 'A simple agent that says hello.',
+  protocolVersion: '0.3.0',
+  version: '0.1.0',
+  url: 'http://localhost:4000/a2a/jsonrpc', // The public URL of your agent server
+  skills: [{ id: 'chat', name: 'Chat', description: 'Say hello', tags: ['chat'] }],
+  capabilities: {
+    pushNotifications: false,
+  },
+  defaultInputModes: ['text'],
+  defaultOutputModes: ['text'],
+  additionalInterfaces: [
+    { url: 'http://localhost:4000/a2a/jsonrpc', transport: 'JSONRPC' }, // Default JSON-RPC transport
+    { url: 'http://localhost:4000/a2a/rest', transport: 'HTTP+JSON' }, // HTTP+JSON/REST transport
+  ],
 };
 
 // 2. Implement the agent's logic.
 class HelloExecutor implements AgentExecutor {
-  async execute(
-    requestContext: RequestContext,
-    eventBus: ExecutionEventBus
-  ): Promise<void> {
+  async execute(requestContext: RequestContext, eventBus: ExecutionEventBus): Promise<void> {
     // Create a direct message response.
     const responseMessage: Message = {
-      kind: "message",
+      kind: 'message',
       messageId: uuidv4(),
-      role: "agent",
-      parts: [{ kind: "text", text: "Hello, world!" }],
+      role: 'agent',
+      parts: [{ kind: 'text', text: 'Hello, world!' }],
       // Associate the response with the incoming request's context.
       contextId: requestContext.contextId,
     };
@@ -86,7 +128,7 @@ class HelloExecutor implements AgentExecutor {
     eventBus.publish(responseMessage);
     eventBus.finished();
   }
-  
+
   // cancelTask is not needed for this simple, non-stateful agent.
   cancelTask = async (): Promise<void> => {};
 }
@@ -99,51 +141,56 @@ const requestHandler = new DefaultRequestHandler(
   agentExecutor
 );
 
-const appBuilder = new A2AExpressApp(requestHandler);
-const expressApp = appBuilder.setupRoutes(express());
+const app = express();
 
-expressApp.listen(4000, () => {
+app.use(`/${AGENT_CARD_PATH}`, agentCardHandler({ agentCardProvider: requestHandler }));
+app.use('/a2a/jsonrpc', jsonRpcHandler({ requestHandler, userBuilder: UserBuilder.noAuthentication }));
+app.use('/a2a/rest', restHandler({ requestHandler, userBuilder: UserBuilder.noAuthentication }));
+
+app.listen(4000, () => {
   console.log(`🚀 Server started on http://localhost:4000`);
 });
 ```
 
 ### Client: Sending a Message
 
-The `A2AClient` makes it easy to communicate with any A2A-compliant agent.
+The [`ClientFactory`](src/client/factory.ts) makes it easy to communicate with any A2A-compliant agent.
 
 ```typescript
 // client.ts
-import { A2AClient, SendMessageSuccessResponse } from "@a2a-js/sdk/client";
-import { Message, MessageSendParams } from "@a2a-js/sdk";
-import { v4 as uuidv4 } from "uuid";
+import { ClientFactory } from '@mailmodo/a2a/client';
+import { Message, MessageSendParams, SendMessageSuccessResponse } from '@mailmodo/a2a';
+import { v4 as uuidv4 } from 'uuid';
 
 async function run() {
-  // Create a client pointing to the agent's Agent Card URL.
-  const client = await A2AClient.fromCardUrl("http://localhost:4000/.well-known/agent-card.json");
+  const factory = new ClientFactory();
+
+  // createFromUrl accepts baseUrl and optional path,
+  // (the default path is /.well-known/agent-card.json)
+  const client = await factory.createFromUrl('http://localhost:4000');
 
   const sendParams: MessageSendParams = {
     message: {
       messageId: uuidv4(),
-      role: "user",
-      parts: [{ kind: "text", text: "Hi there!" }],
-      kind: "message",
+      role: 'user',
+      parts: [{ kind: 'text', text: 'Hi there!' }],
+      kind: 'message',
     },
   };
 
-  const response = await client.sendMessage(sendParams);
-
-  if ("error" in response) {
-    console.error("Error:", response.error.message);
-  } else {
-    const result = (response as SendMessageSuccessResponse).result as Message;
-    console.log("Agent response:", result.parts[0].text); // "Hello, world!"
+  try {
+    const response = await client.sendMessage(sendParams);
+    const result = response as Message;
+    console.log('Agent response:', result.parts[0].text); // "Hello, world!"
+  } catch(e) {
+    console.error('Error:', e);
   }
 }
 
 await run();
 ```
 
------
+---
 
 ## A2A `Task` Support
 
@@ -155,47 +202,47 @@ This agent creates a task, attaches a file artifact to it, and marks it as compl
 
 ```typescript
 // server.ts
-import { Task, TaskArtifactUpdateEvent, TaskStatusUpdateEvent } from "@a2a-js/sdk";
+import { Task, TaskArtifactUpdateEvent, TaskStatusUpdateEvent } from '@mailmodo/a2a';
 // ... other imports from the quickstart server ...
 
 class TaskExecutor implements AgentExecutor {
-  async execute(
-    requestContext: RequestContext,
-    eventBus: ExecutionEventBus
-  ): Promise<void> {
-    const { taskId, contextId } = requestContext;
-
-    // 1. Create and publish the initial task object.
-    const initialTask: Task = {
-      kind: "task",
-      id: taskId,
-      contextId: contextId,
-      status: {
-        state: "submitted",
-        timestamp: new Date().toISOString(),
-      },
-    };
-    eventBus.publish(initialTask);
+  async execute(requestContext: RequestContext, eventBus: ExecutionEventBus): Promise<void> {
+    const { taskId, contextId, userMessage, task } = requestContext;
+
+    // 1. Create and publish the initial task object if it doesn't exist.
+    if (!task) {
+      const initialTask: Task = {
+        kind: 'task',
+        id: taskId,
+        contextId: contextId,
+        status: {
+          state: 'submitted',
+          timestamp: new Date().toISOString(),
+        },
+        history: [userMessage],
+      };
+      eventBus.publish(initialTask);
+    }
 
     // 2. Create and publish an artifact.
     const artifactUpdate: TaskArtifactUpdateEvent = {
-      kind: "artifact-update",
+      kind: 'artifact-update',
       taskId: taskId,
       contextId: contextId,
       artifact: {
-        artifactId: "report-1",
-        name: "analysis_report.txt",
-        parts: [{ kind: "text", text: `This is the analysis for task ${taskId}.` }],
+        artifactId: 'report-1',
+        name: 'analysis_report.txt',
+        parts: [{ kind: 'text', text: `This is the analysis for task ${taskId}.` }],
       },
     };
     eventBus.publish(artifactUpdate);
 
     // 3. Publish the final status and mark the event as 'final'.
     const finalUpdate: TaskStatusUpdateEvent = {
-      kind: "status-update",
+      kind: 'status-update',
       taskId: taskId,
       contextId: contextId,
-      status: { state: "completed", timestamp: new Date().toISOString() },
+      status: { state: 'completed', timestamp: new Date().toISOString() },
       final: true,
     };
     eventBus.publish(finalUpdate);
@@ -212,21 +259,28 @@ The client sends a message and receives a `Task` object as the result.
 
 ```typescript
 // client.ts
-import { A2AClient, SendMessageSuccessResponse } from "@a2a-js/sdk/client";
-import { Message, MessageSendParams, Task } from "@a2a-js/sdk";
+import { ClientFactory } from '@mailmodo/a2a/client';
+import { Message, MessageSendParams, SendMessageSuccessResponse, Task } from '@mailmodo/a2a';
 // ... other imports ...
 
-const client = await A2AClient.fromCardUrl("http://localhost:4000/.well-known/agent-card.json");
+const factory = new ClientFactory();
 
-const response = await client.sendMessage({ message: { messageId: uuidv4(), role: "user", parts: [{ kind: "text", text: "Do something." }], kind: "message" } });
+// createFromUrl accepts baseUrl and optional path,
+// (the default path is /.well-known/agent-card.json)
+const client = await factory.createFromUrl('http://localhost:4000');
 
-if ("error" in response) {
-  console.error("Error:", response.error.message);
-} else {
-  const result = (response as SendMessageSuccessResponse).result;
+try {
+  const result = await client.sendMessage({
+    message: {
+      messageId: uuidv4(),
+      role: 'user',
+      parts: [{ kind: 'text', text: 'Do something.' }],
+      kind: 'message',
+    },
+  });
 
   // Check if the agent's response is a Task or a direct Message.
-  if (result.kind === "task") {
+  if (result.kind === 'task') {
     const task = result as Task;
     console.log(`Task [${task.id}] completed with status: ${task.status.state}`);
 
@@ -236,52 +290,99 @@ if ("error" in response) {
     }
   } else {
     const message = result as Message;
-    console.log("Received direct message:", message.parts[0].text);
+    console.log('Received direct message:', message.parts[0].text);
   }
+} catch (e) {
+  console.error('Error:', e);
 }
 ```
 
------
+---
 
 ## Client Customization
 
-You can provide a custom `fetch` implementation to the `A2AClient` to modify its HTTP request behavior. Common use cases include:
+Client can be customized via [`CallInterceptor`'s](src/client/interceptors.ts) which is a recommended way as it's transport-agnostic.
+
+Common use cases include:
 
-  * **Request Interception**: Log outgoing requests or collect metrics.
-  * **Header Injection**: Add custom headers for authentication, tracing, or routing.
-  * **Retry Mechanisms**: Implement custom logic for retrying failed requests.
+- **Request Interception**: Log outgoing requests or collect metrics.
+- **Header Injection**: Add custom headers for authentication, tracing, or routing.
+- **A2A Extensions**: Modifying payloads to include protocol extension data.
 
 ### Example: Injecting a Custom Header
 
-This example creates a `fetch` wrapper that adds a unique `X-Request-ID` to every outgoing request.
+This example defines a `CallInterceptor` to update `serviceParameters` which are passed as HTTP headers.
 
 ```typescript
-import { A2AClient } from "@a2a-js/sdk/client";
-import { v4 as uuidv4 } from "uuid";
-
-// 1. Create a wrapper around the global fetch function.
-const fetchWithCustomHeader: typeof fetch = async (url, init) => {
-  const headers = new Headers(init?.headers);
-  headers.set("X-Request-ID", uuidv4());
-
-  const newInit = { ...init, headers };
-  
-  console.log(`Sending request to ${url} with X-Request-ID: ${headers.get("X-Request-ID")}`);
-  
-  return fetch(url, newInit);
-};
+import { v4 as uuidv4 } from 'uuid';
+import { AfterArgs, BeforeArgs, CallInterceptor, ClientFactory, ClientFactoryOptions } from '@mailmodo/a2a/client';
+
+// 1. Define an interceptor
+class RequestIdInterceptor implements CallInterceptor {
+  before(args: BeforeArgs): Promise<void> {
+    args.options = {
+      ...args.options,
+      serviceParameters: {
+        ...args.options.serviceParameters,
+        ['X-Request-ID']: uuidv4(),
+      },
+    };
+    return Promise.resolve();
+  }
 
-// 2. Provide the custom fetch implementation to the client.
-const client = await A2AClient.fromCardUrl(
-  "http://localhost:4000/.well-known/agent-card.json",
-  { fetchImpl: fetchWithCustomHeader }
-);
+  after(): Promise<void> {
+    return Promise.resolve();
+  }
+}
+
+// 2. Register the interceptor in the client factory
+const factory = new ClientFactory(ClientFactoryOptions.createFrom(ClientFactoryOptions.default, {
+  clientConfig: {
+    interceptors: [new RequestIdInterceptor()]
+  }
+}))
+const client = await factory.createFromAgentCardUrl('http://localhost:4000');
+
+// Now, all requests made by clients created by this factory will include the X-Request-ID header.
+await client.sendMessage({
+  message: {
+    messageId: uuidv4(),
+    role: 'user',
+    parts: [{ kind: 'text', text: 'A message requiring custom headers.' }],
+    kind: 'message',
+  },
+});
+```
+
+### Example: Specifying a Timeout
+
+Each client method can be configured with an optional `signal` field.
+
+```typescript
+import { ClientFactory } from '@mailmodo/a2a/client';
+
+const factory = new ClientFactory();
+
+// createFromUrl accepts baseUrl and optional path,
+// (the default path is /.well-known/agent-card.json)
+const client = await factory.createFromUrl('http://localhost:4000');
 
-// Now, all requests made by this client instance will include the X-Request-ID header.
-await client.sendMessage({ message: { messageId: uuidv4(), role: "user", parts: [{ kind: "text", text: "A message requiring custom headers." }], kind: "message" } });
+await client.sendMessage(
+  {
+    message: {
+      messageId: uuidv4(),
+      role: 'user',
+      parts: [{ kind: 'text', text: 'A long-running message.' }],
+      kind: 'message',
+    },
+  },
+  {
+    signal: AbortSignal.timeout(5000), // 5 seconds timeout
+  }
+);
 ```
 
-### Using the Provided `AuthenticationHandler`
+### Customizing Transports: Using the Provided `AuthenticationHandler`
 
 For advanced authentication scenarios, the SDK includes a higher-order function `createAuthenticatingFetchWithRetry` and an `AuthenticationHandler` interface. This utility automatically adds authorization headers and can retry requests that fail with authentication errors (e.g., 401 Unauthorized).
 
@@ -289,16 +390,18 @@ Here's how to use it to manage a Bearer token:
 
 ```typescript
 import {
-  A2AClient,
+  ClientFactory,
+  ClientFactoryOptions,
+  JsonRpcTransportFactory,
   AuthenticationHandler,
   createAuthenticatingFetchWithRetry,
-} from "@a2a-js/sdk/client";
+} from '@mailmodo/a2a/client';
 
 // A simple token provider that simulates fetching a new token.
 const tokenProvider = {
-  token: "initial-stale-token",
+  token: 'initial-stale-token',
   getNewToken: async () => {
-    console.log("Refreshing auth token...");
+    console.log('Refreshing auth token...');
     tokenProvider.token = `new-token-${Date.now()}`;
     return tokenProvider.token;
   },
@@ -314,7 +417,8 @@ const handler: AuthenticationHandler = {
   // shouldRetryWithHeaders() is called after a request fails.
   // It decides if a retry is needed and provides new headers.
   shouldRetryWithHeaders: async (req: RequestInit, res: Response) => {
-    if (res.status === 401) { // Unauthorized
+    if (res.status === 401) {
+      // Unauthorized
       const newToken = await tokenProvider.getNewToken();
       // Return new headers to trigger a single retry.
       return { Authorization: `Bearer ${newToken}` };
@@ -328,14 +432,18 @@ const handler: AuthenticationHandler = {
 // 2. Create the authenticated fetch function.
 const authFetch = createAuthenticatingFetchWithRetry(fetch, handler);
 
-// 3. Initialize the client with the new fetch implementation.
-const client = await A2AClient.fromCardUrl(
-  "http://localhost:4000/.well-known/agent-card.json",
-  { fetchImpl: authFetch }
-);
+// 3. Inject new fetch implementation into a client factory.
+const factory = new ClientFactory(ClientFactoryOptions.createFrom(ClientFactoryOptions.default, {
+  transports: [
+    new JsonRpcTransportFactory({ fetchImpl: authFetch })
+  ]
+}))
+
+// 4. Clients created from the factory are going to have custom fetch attached.
+const client = await factory.createFromUrl('http://localhost:4000');
 ```
 
------
+---
 
 ## Streaming
 
@@ -350,44 +458,48 @@ The agent publishes events as it works on the task. The client receives these ev
 // ... imports ...
 
 class StreamingExecutor implements AgentExecutor {
-  async execute(
-    requestContext: RequestContext,
-    eventBus: ExecutionEventBus
-  ): Promise<void> {
-    const { taskId, contextId } = requestContext;
-
-    // 1. Publish initial 'submitted' state.
-    eventBus.publish({
-      kind: "task",
-      id: taskId,
-      contextId,
-      status: { state: "submitted", timestamp: new Date().toISOString() },
-    });
+  async execute(requestContext: RequestContext, eventBus: ExecutionEventBus): Promise<void> {
+    const { taskId, contextId, userMessage, task } = requestContext;
+
+    // 1. Create and publish the initial task object if it doesn't exist.
+    if (!task) {
+      const initialTask: Task = {
+        kind: 'task',
+        id: taskId,
+        contextId: contextId,
+        status: {
+          state: 'submitted',
+          timestamp: new Date().toISOString(),
+        },
+        history: [userMessage],
+      };
+      eventBus.publish(initialTask);
+    }
 
     // 2. Publish 'working' state.
     eventBus.publish({
-      kind: "status-update",
+      kind: 'status-update',
       taskId,
       contextId,
-      status: { state: "working", timestamp: new Date().toISOString() },
-      final: false
+      status: { state: 'working', timestamp: new Date().toISOString() },
+      final: false,
     });
 
     // 3. Simulate work and publish an artifact.
-    await new Promise(resolve => setTimeout(resolve, 1000));
+    await new Promise((resolve) => setTimeout(resolve, 1000));
     eventBus.publish({
-      kind: "artifact-update",
+      kind: 'artifact-update',
       taskId,
       contextId,
-      artifact: { artifactId: "result.txt", parts: [{ kind: "text", text: "First result." }] },
+      artifact: { artifactId: 'result.txt', parts: [{ kind: 'text', text: 'First result.' }] },
     });
 
     // 4. Publish final 'completed' state.
     eventBus.publish({
-      kind: "status-update",
+      kind: 'status-update',
       taskId,
       contextId,
-      status: { state: "completed", timestamp: new Date().toISOString() },
+      status: { state: 'completed', timestamp: new Date().toISOString() },
       final: true,
     });
     eventBus.finished();
@@ -402,20 +514,24 @@ The `sendMessageStream` method returns an `AsyncGenerator` that yields events as
 
 ```typescript
 // client.ts
-import { A2AClient } from "@a2a-js/sdk/client";
-import { MessageSendParams } from "@a2a-js/sdk";
-import { v4 as uuidv4 } from "uuid";
+import { ClientFactory } from '@mailmodo/a2a/client';
+import { MessageSendParams } from '@mailmodo/a2a';
+import { v4 as uuidv4 } from 'uuid';
 // ... other imports ...
 
-const client = await A2AClient.fromCardUrl("http://localhost:4000/.well-known/agent-card.json");
+const factory = new ClientFactory();
+
+// createFromUrl accepts baseUrl and optional path,
+// (the default path is /.well-known/agent-card.json)
+const client = await factory.createFromUrl('http://localhost:4000');
 
 async function streamTask() {
   const streamParams: MessageSendParams = {
     message: {
       messageId: uuidv4(),
-      role: "user",
-      parts: [{ kind: "text", text: "Stream me some updates!" }],
-      kind: "message",
+      role: 'user',
+      parts: [{ kind: 'text', text: 'Stream me some updates!' }],
+      kind: 'message',
     },
   };
 
@@ -423,17 +539,17 @@ async function streamTask() {
     const stream = client.sendMessageStream(streamParams);
 
     for await (const event of stream) {
-      if (event.kind === "task") {
+      if (event.kind === 'task') {
         console.log(`[${event.id}] Task created. Status: ${event.status.state}`);
-      } else if (event.kind === "status-update") {
+      } else if (event.kind === 'status-update') {
         console.log(`[${event.taskId}] Status Updated: ${event.status.state}`);
-      } else if (event.kind === "artifact-update") {
+      } else if (event.kind === 'artifact-update') {
         console.log(`[${event.taskId}] Artifact Received: ${event.artifact.artifactId}`);
       }
     }
-    console.log("--- Stream finished ---");
+    console.log('--- Stream finished ---');
   } catch (error) {
-    console.error("Error during streaming:", error);
+    console.error('Error during streaming:', error);
   }
 }
 
@@ -457,7 +573,7 @@ import {
   RequestContext,
   ExecutionEventBus,
   TaskStatusUpdateEvent,
-} from "@a2a-js/sdk/server";
+} from '@mailmodo/a2a/server';
 // ... other imports ...
 
 class CancellableExecutor implements AgentExecutor {
@@ -468,26 +584,20 @@ class CancellableExecutor implements AgentExecutor {
    * When a cancellation is requested, add the taskId to our tracking set.
    * The `execute` loop will handle the rest.
    */
-  public async cancelTask(
-    taskId: string,
-    eventBus: ExecutionEventBus,
-  ): Promise<void> {
+  public async cancelTask(taskId: string, eventBus: ExecutionEventBus): Promise<void> {
     console.log(`[Executor] Received cancellation request for task: ${taskId}`);
     this.cancelledTasks.add(taskId);
   }
 
-  public async execute(
-    requestContext: RequestContext,
-    eventBus: ExecutionEventBus,
-  ): Promise<void> {
+  public async execute(requestContext: RequestContext, eventBus: ExecutionEventBus): Promise<void> {
     const { taskId, contextId } = requestContext;
 
     // Start the task
     eventBus.publish({
-      kind: "status-update",
+      kind: 'status-update',
       taskId,
       contextId,
-      status: { state: "working", timestamp: new Date().toISOString() },
+      status: { state: 'working', timestamp: new Date().toISOString() },
       final: false,
     });
 
@@ -497,18 +607,18 @@ class CancellableExecutor implements AgentExecutor {
       // Before each step, check if the task has been canceled.
       if (this.cancelledTasks.has(taskId)) {
         console.log(`[Executor] Aborting task ${taskId} due to cancellation.`);
-        
+
         // Publish the final 'canceled' status.
         const cancelledUpdate: TaskStatusUpdateEvent = {
-          kind: "status-update",
+          kind: 'status-update',
           taskId: taskId,
           contextId: contextId,
-          status: { state: "canceled", timestamp: new Date().toISOString() },
+          status: { state: 'canceled', timestamp: new Date().toISOString() },
           final: true,
         };
         eventBus.publish(cancelledUpdate);
         eventBus.finished();
-        
+
         // Clean up and exit.
         this.cancelledTasks.delete(taskId);
         return;
@@ -516,17 +626,17 @@ class CancellableExecutor implements AgentExecutor {
 
       // Simulate one step of work.
       console.log(`[Executor] Working on step ${i + 1} for task ${taskId}...`);
-      await new Promise(resolve => setTimeout(resolve, 1000));
+      await new Promise((resolve) => setTimeout(resolve, 1000));
     }
 
     console.log(`[Executor] Task ${taskId} finished all steps without cancellation.`);
 
     // If not canceled, finish the work and publish the completed state.
     const finalUpdate: TaskStatusUpdateEvent = {
-      kind: "status-update",
+      kind: 'status-update',
       taskId,
       contextId,
-      status: { state: "completed", timestamp: new Date().toISOString() },
+      status: { state: 'completed', timestamp: new Date().toISOString() },
       final: true,
     };
     eventBus.publish(finalUpdate);
@@ -535,10 +645,112 @@ class CancellableExecutor implements AgentExecutor {
 }
 ```
 
+## A2A Push Notifications
+
+For very long-running tasks (e.g., lasting minutes, hours, or even days) or when clients cannot or prefer not to maintain persistent connections (like mobile clients or serverless functions), A2A supports asynchronous updates via push notifications. This mechanism allows the A2A Server to actively notify a client-provided webhook when a significant task update occurs.
+
+### Server-Side Configuration
+
+To enable push notifications, your agent card must declare support:
+
+```typescript
+const movieAgentCard: AgentCard = {
+  // ... other properties
+  capabilities: {
+    streaming: true,
+    pushNotifications: true, // Enable push notifications
+    stateTransitionHistory: true,
+  },
+  // ... rest of agent card
+};
+```
+
+When creating the `DefaultRequestHandler`, you can optionally provide custom push notification components:
+
+```typescript
+import {
+  DefaultRequestHandler,
+  InMemoryPushNotificationStore,
+  DefaultPushNotificationSender,
+} from '@mailmodo/a2a/server';
+
+// Optional: Custom push notification store and sender
+const pushNotificationStore = new InMemoryPushNotificationStore();
+const pushNotificationSender = new DefaultPushNotificationSender(pushNotificationStore, {
+  timeout: 5000, // 5 second timeout
+  tokenHeaderName: 'X-A2A-Notification-Token', // Custom header name
+});
+
+const requestHandler = new DefaultRequestHandler(
+  movieAgentCard,
+  taskStore,
+  agentExecutor,
+  undefined, // eventBusManager (optional)
+  pushNotificationStore, // custom store
+  pushNotificationSender, // custom sender
+  undefined // extendedAgentCard (optional)
+);
+```
+
+### Client-Side Usage
+
+Configure push notifications when sending messages:
+
+```typescript
+// Configure push notification for a message
+const pushConfig: PushNotificationConfig = {
+  id: 'my-notification-config', // Optional, defaults to task ID
+  url: 'https://my-app.com/webhook/task-updates',
+  token: 'your-auth-token', // Optional authentication token
+};
+
+const sendParams: MessageSendParams = {
+  message: {
+    messageId: uuidv4(),
+    role: 'user',
+    parts: [{ kind: 'text', text: 'Hello, agent!' }],
+    kind: 'message',
+  },
+  configuration: {
+    blocking: true,
+    acceptedOutputModes: ['text/plain'],
+    pushNotificationConfig: pushConfig, // Add push notification config
+  },
+};
+```
+
+### Webhook Endpoint Implementation
+
+Your webhook endpoint should expect POST requests with the task data:
+
+```typescript
+// Example Express.js webhook endpoint
+app.post('/webhook/task-updates', (req, res) => {
+  const task = req.body; // The complete task object
+
+  // Verify the token if provided
+  const token = req.headers['x-a2a-notification-token'];
+  if (token !== 'your-auth-token') {
+    return res.status(401).json({ error: 'Unauthorized' });
+  }
+
+  console.log(`Task ${task.id} status: ${task.status.state}`);
+
+  // Process the task update
+  // ...
+
+  res.status(200).json({ received: true });
+});
+```
+
 ## License
 
-This project is licensed under the terms of the [Apache 2.0 License](https://raw.githubusercontent.com/google-a2a/a2a-python/refs/heads/main/LICENSE).
+This project is licensed under the terms of the [Apache 2.0 License](LICENSE).
+
+## Upstream & Contributing
+
+This is a customized fork of the [official A2A JavaScript SDK](https://github.com/a2aproject/a2a-js) maintained by Mailmodo.
 
-## Contributing
+For contributing to the upstream project, see the [upstream CONTRIBUTING.md](https://github.com/a2aproject/a2a-js/blob/main/CONTRIBUTING.md).
 
-See [CONTRIBUTING.md](https://github.com/google-a2a/a2a-js/blob/main/CONTRIBUTING.md) for contribution guidelines.
+For issues or contributions specific to this Mailmodo edition, please contact the Mailmodo team.