@a2a-js/sdk 0.3.3 → 0.3.4

package/README.md

@@ -535,6 +535,107 @@ 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 "@a2a-js/sdk/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).

package/dist/client/index.cjs

@@ -243,6 +243,28 @@ var A2AClient = class _A2AClient {
       params
     );
   }
+  /**
+   * Lists the push notification configurations for a given task.
+   * @param params Parameters containing the taskId.
+   * @returns A Promise resolving to ListTaskPushNotificationConfigResponse.
+   */
+  async listTaskPushNotificationConfig(params) {
+    return this._postRpcRequest(
+      "tasks/pushNotificationConfig/list",
+      params
+    );
+  }
+  /**
+   * Deletes the push notification configuration for a given task.
+   * @param params Parameters containing the taskId and push notification configuration ID.
+   * @returns A Promise resolving to DeleteTaskPushNotificationConfigResponse.
+   */
+  async deleteTaskPushNotificationConfig(params) {
+    return this._postRpcRequest(
+      "tasks/pushNotificationConfig/delete",
+      params
+    );
+  }
   /**
    * Retrieves a task by its ID.
    * @param params Parameters containing the taskId and optional historyLength.
@@ -259,6 +281,17 @@ var A2AClient = class _A2AClient {
   async cancelTask(params) {
     return this._postRpcRequest("tasks/cancel", params);
   }
+  /**
+   * @template TExtensionParams The type of parameters for the custom extension method.
+   * @template TExtensionResponse The type of response expected from the custom extension method. 
+   * This should extend JSONRPCResponse. This ensures the extension response is still a valid A2A response.
+   * @param method Custom JSON-RPC method defined in the AgentCard's extensions.
+   * @param params Extension paramters defined in the AgentCard's extensions.
+   * @returns A Promise that resolves to the RPC response.
+   */
+  async callExtensionMethod(method, params) {
+    return this._postRpcRequest(method, params);
+  }
   /**
    * Resubscribes to a task's event stream using Server-Sent Events (SSE).
    * This is used if a previous SSE connection for an active task was broken.

package/dist/client/index.d.cts

@@ -1,4 +1,4 @@
-import { ac as AgentCard, w as MessageSendParams, S as SendMessageResponse, B as Message, aw as Task, aO as TaskStatusUpdateEvent, aQ as TaskArtifactUpdateEvent, Z as TaskPushNotificationConfig, b as SetTaskPushNotificationConfigResponse, X as TaskIdParams, c as GetTaskPushNotificationConfigResponse, V as TaskQueryParams, G as GetTaskResponse, C as CancelTaskResponse, i as JSONRPCResponse, J as JSONRPCErrorResponse } from '../types-DNKcmF0f.cjs';
+import { ac as AgentCard, w as MessageSendParams, S as SendMessageResponse, B as Message, aw as Task, aO as TaskStatusUpdateEvent, aQ as TaskArtifactUpdateEvent, Z as TaskPushNotificationConfig, b as SetTaskPushNotificationConfigResponse, X as TaskIdParams, c as GetTaskPushNotificationConfigResponse, a5 as ListTaskPushNotificationConfigParams, j as ListTaskPushNotificationConfigResponse, a7 as DeleteTaskPushNotificationConfigParams, g as DeleteTaskPushNotificationConfigResponse, V as TaskQueryParams, G as GetTaskResponse, C as CancelTaskResponse, i as JSONRPCResponse, J as JSONRPCErrorResponse } from '../types-DNKcmF0f.cjs';
 
 type A2AStreamEventData = Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent;
 interface A2AClientOptions {
@@ -81,6 +81,18 @@ declare class A2AClient {
      * @returns A Promise resolving to GetTaskPushNotificationConfigResponse.
      */
     getTaskPushNotificationConfig(params: TaskIdParams): Promise<GetTaskPushNotificationConfigResponse>;
+    /**
+     * Lists the push notification configurations for a given task.
+     * @param params Parameters containing the taskId.
+     * @returns A Promise resolving to ListTaskPushNotificationConfigResponse.
+     */
+    listTaskPushNotificationConfig(params: ListTaskPushNotificationConfigParams): Promise<ListTaskPushNotificationConfigResponse>;
+    /**
+     * Deletes the push notification configuration for a given task.
+     * @param params Parameters containing the taskId and push notification configuration ID.
+     * @returns A Promise resolving to DeleteTaskPushNotificationConfigResponse.
+     */
+    deleteTaskPushNotificationConfig(params: DeleteTaskPushNotificationConfigParams): Promise<DeleteTaskPushNotificationConfigResponse>;
     /**
      * Retrieves a task by its ID.
      * @param params Parameters containing the taskId and optional historyLength.
@@ -93,6 +105,15 @@ declare class A2AClient {
      * @returns A Promise resolving to CancelTaskResponse, which contains the updated Task object or an error.
      */
     cancelTask(params: TaskIdParams): Promise<CancelTaskResponse>;
+    /**
+     * @template TExtensionParams The type of parameters for the custom extension method.
+     * @template TExtensionResponse The type of response expected from the custom extension method.
+     * This should extend JSONRPCResponse. This ensures the extension response is still a valid A2A response.
+     * @param method Custom JSON-RPC method defined in the AgentCard's extensions.
+     * @param params Extension paramters defined in the AgentCard's extensions.
+     * @returns A Promise that resolves to the RPC response.
+     */
+    callExtensionMethod<TExtensionParams, TExtensionResponse extends JSONRPCResponse>(method: string, params: TExtensionParams): Promise<TExtensionResponse>;
     /**
      * Resubscribes to a task's event stream using Server-Sent Events (SSE).
      * This is used if a previous SSE connection for an active task was broken.

package/dist/client/index.d.ts

@@ -1,4 +1,4 @@
-import { ac as AgentCard, w as MessageSendParams, S as SendMessageResponse, B as Message, aw as Task, aO as TaskStatusUpdateEvent, aQ as TaskArtifactUpdateEvent, Z as TaskPushNotificationConfig, b as SetTaskPushNotificationConfigResponse, X as TaskIdParams, c as GetTaskPushNotificationConfigResponse, V as TaskQueryParams, G as GetTaskResponse, C as CancelTaskResponse, i as JSONRPCResponse, J as JSONRPCErrorResponse } from '../types-DNKcmF0f.js';
+import { ac as AgentCard, w as MessageSendParams, S as SendMessageResponse, B as Message, aw as Task, aO as TaskStatusUpdateEvent, aQ as TaskArtifactUpdateEvent, Z as TaskPushNotificationConfig, b as SetTaskPushNotificationConfigResponse, X as TaskIdParams, c as GetTaskPushNotificationConfigResponse, a5 as ListTaskPushNotificationConfigParams, j as ListTaskPushNotificationConfigResponse, a7 as DeleteTaskPushNotificationConfigParams, g as DeleteTaskPushNotificationConfigResponse, V as TaskQueryParams, G as GetTaskResponse, C as CancelTaskResponse, i as JSONRPCResponse, J as JSONRPCErrorResponse } from '../types-DNKcmF0f.js';
 
 type A2AStreamEventData = Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent;
 interface A2AClientOptions {
@@ -81,6 +81,18 @@ declare class A2AClient {
      * @returns A Promise resolving to GetTaskPushNotificationConfigResponse.
      */
     getTaskPushNotificationConfig(params: TaskIdParams): Promise<GetTaskPushNotificationConfigResponse>;
+    /**
+     * Lists the push notification configurations for a given task.
+     * @param params Parameters containing the taskId.
+     * @returns A Promise resolving to ListTaskPushNotificationConfigResponse.
+     */
+    listTaskPushNotificationConfig(params: ListTaskPushNotificationConfigParams): Promise<ListTaskPushNotificationConfigResponse>;
+    /**
+     * Deletes the push notification configuration for a given task.
+     * @param params Parameters containing the taskId and push notification configuration ID.
+     * @returns A Promise resolving to DeleteTaskPushNotificationConfigResponse.
+     */
+    deleteTaskPushNotificationConfig(params: DeleteTaskPushNotificationConfigParams): Promise<DeleteTaskPushNotificationConfigResponse>;
     /**
      * Retrieves a task by its ID.
      * @param params Parameters containing the taskId and optional historyLength.
@@ -93,6 +105,15 @@ declare class A2AClient {
      * @returns A Promise resolving to CancelTaskResponse, which contains the updated Task object or an error.
      */
     cancelTask(params: TaskIdParams): Promise<CancelTaskResponse>;
+    /**
+     * @template TExtensionParams The type of parameters for the custom extension method.
+     * @template TExtensionResponse The type of response expected from the custom extension method.
+     * This should extend JSONRPCResponse. This ensures the extension response is still a valid A2A response.
+     * @param method Custom JSON-RPC method defined in the AgentCard's extensions.
+     * @param params Extension paramters defined in the AgentCard's extensions.
+     * @returns A Promise that resolves to the RPC response.
+     */
+    callExtensionMethod<TExtensionParams, TExtensionResponse extends JSONRPCResponse>(method: string, params: TExtensionParams): Promise<TExtensionResponse>;
     /**
      * Resubscribes to a task's event stream using Server-Sent Events (SSE).
      * This is used if a previous SSE connection for an active task was broken.

package/dist/client/index.js

@@ -218,6 +218,28 @@ var A2AClient = class _A2AClient {
       params
     );
   }
+  /**
+   * Lists the push notification configurations for a given task.
+   * @param params Parameters containing the taskId.
+   * @returns A Promise resolving to ListTaskPushNotificationConfigResponse.
+   */
+  async listTaskPushNotificationConfig(params) {
+    return this._postRpcRequest(
+      "tasks/pushNotificationConfig/list",
+      params
+    );
+  }
+  /**
+   * Deletes the push notification configuration for a given task.
+   * @param params Parameters containing the taskId and push notification configuration ID.
+   * @returns A Promise resolving to DeleteTaskPushNotificationConfigResponse.
+   */
+  async deleteTaskPushNotificationConfig(params) {
+    return this._postRpcRequest(
+      "tasks/pushNotificationConfig/delete",
+      params
+    );
+  }
   /**
    * Retrieves a task by its ID.
    * @param params Parameters containing the taskId and optional historyLength.
@@ -234,6 +256,17 @@ var A2AClient = class _A2AClient {
   async cancelTask(params) {
     return this._postRpcRequest("tasks/cancel", params);
   }
+  /**
+   * @template TExtensionParams The type of parameters for the custom extension method.
+   * @template TExtensionResponse The type of response expected from the custom extension method. 
+   * This should extend JSONRPCResponse. This ensures the extension response is still a valid A2A response.
+   * @param method Custom JSON-RPC method defined in the AgentCard's extensions.
+   * @param params Extension paramters defined in the AgentCard's extensions.
+   * @returns A Promise that resolves to the RPC response.
+   */
+  async callExtensionMethod(method, params) {
+    return this._postRpcRequest(method, params);
+  }
   /**
    * Resubscribes to a task's event stream using Server-Sent Events (SSE).
    * This is used if a previous SSE connection for an active task was broken.

package/dist/server/index.cjs

@@ -22,8 +22,10 @@ __export(server_exports, {
   A2AError: () => A2AError,
   DefaultExecutionEventBus: () => DefaultExecutionEventBus,
   DefaultExecutionEventBusManager: () => DefaultExecutionEventBusManager,
+  DefaultPushNotificationSender: () => DefaultPushNotificationSender,
   DefaultRequestHandler: () => DefaultRequestHandler,
   ExecutionEventQueue: () => ExecutionEventQueue,
+  InMemoryPushNotificationStore: () => InMemoryPushNotificationStore,
   InMemoryTaskStore: () => InMemoryTaskStore,
   JsonRpcTransportHandler: () => JsonRpcTransportHandler,
   RequestContext: () => RequestContext,
@@ -366,6 +368,97 @@ var ResultManager = class {
   }
 };
 
+// src/server/push_notification/push_notification_store.ts
+var InMemoryPushNotificationStore = class {
+  store = /* @__PURE__ */ new Map();
+  async save(taskId, pushNotificationConfig) {
+    const configs = this.store.get(taskId) || [];
+    if (!pushNotificationConfig.id) {
+      pushNotificationConfig.id = taskId;
+    }
+    const existingIndex = configs.findIndex((config) => config.id === pushNotificationConfig.id);
+    if (existingIndex !== -1) {
+      configs.splice(existingIndex, 1);
+    }
+    configs.push(pushNotificationConfig);
+    this.store.set(taskId, configs);
+  }
+  async load(taskId) {
+    const configs = this.store.get(taskId);
+    return configs || [];
+  }
+  async delete(taskId, configId) {
+    if (configId === void 0) {
+      configId = taskId;
+    }
+    const configs = this.store.get(taskId);
+    if (!configs) {
+      return;
+    }
+    const configIndex = configs.findIndex((config) => config.id === configId);
+    if (configIndex !== -1) {
+      configs.splice(configIndex, 1);
+    }
+    if (configs.length === 0) {
+      this.store.delete(taskId);
+    } else {
+      this.store.set(taskId, configs);
+    }
+  }
+};
+
+// src/server/push_notification/default_push_notification_sender.ts
+var DefaultPushNotificationSender = class {
+  pushNotificationStore;
+  options;
+  constructor(pushNotificationStore, options = {}) {
+    this.pushNotificationStore = pushNotificationStore;
+    this.options = {
+      timeout: 5e3,
+      tokenHeaderName: "X-A2A-Notification-Token",
+      ...options
+    };
+  }
+  async send(task) {
+    const pushConfigs = await this.pushNotificationStore.load(task.id);
+    if (!pushConfigs || pushConfigs.length === 0) {
+      return;
+    }
+    pushConfigs.forEach((pushConfig) => {
+      this._dispatchNotification(task, pushConfig).catch((error) => {
+        console.error(`Error sending push notification for task_id=${task.id} to URL: ${pushConfig.url}. Error:`, error);
+      });
+    });
+  }
+  async _dispatchNotification(task, pushConfig) {
+    const url = pushConfig.url;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.options.timeout);
+    try {
+      const headers = {
+        "Content-Type": "application/json"
+      };
+      if (pushConfig.token) {
+        headers[this.options.tokenHeaderName] = pushConfig.token;
+      }
+      const response = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(task),
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      console.info(`Push notification sent for task_id=${task.id} to URL: ${url}`);
+    } catch (error) {
+      console.error(`Error sending push notification for task_id=${task.id} to URL: ${url}. Error:`, error);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+};
+
 // src/server/request_handler/default_request_handler.ts
 var terminalStates = ["completed", "failed", "canceled", "rejected"];
 var DefaultRequestHandler = class {
@@ -374,14 +467,18 @@ var DefaultRequestHandler = class {
   taskStore;
   agentExecutor;
   eventBusManager;
-  // Store for push notification configurations (could be part of TaskStore or separate)
-  pushNotificationConfigs = /* @__PURE__ */ new Map();
-  constructor(agentCard, taskStore, agentExecutor, eventBusManager = new DefaultExecutionEventBusManager(), extendedAgentCard) {
+  pushNotificationStore;
+  pushNotificationSender;
+  constructor(agentCard, taskStore, agentExecutor, eventBusManager = new DefaultExecutionEventBusManager(), pushNotificationStore, pushNotificationSender, extendedAgentCard) {
     this.agentCard = agentCard;
     this.taskStore = taskStore;
     this.agentExecutor = agentExecutor;
     this.eventBusManager = eventBusManager;
     this.extendedAgentCard = extendedAgentCard;
+    if (agentCard.capabilities.pushNotifications) {
+      this.pushNotificationStore = pushNotificationStore || new InMemoryPushNotificationStore();
+      this.pushNotificationSender = pushNotificationSender || new DefaultPushNotificationSender(this.pushNotificationStore);
+    }
   }
   async getAgentCard() {
     return this.agentCard;
@@ -433,6 +530,7 @@ var DefaultRequestHandler = class {
     try {
       for await (const event of eventQueue.events()) {
         await resultManager.processEvent(event);
+        await this._sendPushNotificationIfNeeded(event);
         if (options?.firstResultResolver && !firstResultSent) {
           if (event.kind === "message" || event.kind === "task") {
             options.firstResultResolver(event);
@@ -464,6 +562,9 @@ var DefaultRequestHandler = class {
     resultManager.setContext(incomingMessage);
     const requestContext = await this._createRequestContext(incomingMessage, taskId, false);
     const finalMessageForAgent = requestContext.userMessage;
+    if (params.configuration?.pushNotificationConfig && this.agentCard.capabilities.pushNotifications) {
+      await this.pushNotificationStore?.save(taskId, params.configuration.pushNotificationConfig);
+    }
     const eventBus = this.eventBusManager.createOrGetByTaskId(taskId);
     const eventQueue = new ExecutionEventQueue(eventBus);
     this.agentExecutor.execute(requestContext, eventBus).catch((err) => {
@@ -531,6 +632,9 @@ var DefaultRequestHandler = class {
     const finalMessageForAgent = requestContext.userMessage;
     const eventBus = this.eventBusManager.createOrGetByTaskId(taskId);
     const eventQueue = new ExecutionEventQueue(eventBus);
+    if (params.configuration?.pushNotificationConfig && this.agentCard.capabilities.pushNotifications) {
+      await this.pushNotificationStore?.save(taskId, params.configuration.pushNotificationConfig);
+    }
     this.agentExecutor.execute(requestContext, eventBus).catch((err) => {
       console.error(`Agent execution failed for stream message ${finalMessageForAgent.messageId}:`, err);
       const errorTaskStatus = {
@@ -558,6 +662,7 @@ var DefaultRequestHandler = class {
     try {
       for await (const event of eventQueue.events()) {
         await resultManager.processEvent(event);
+        await this._sendPushNotificationIfNeeded(event);
         yield event;
       }
     } finally {
@@ -622,10 +727,7 @@ var DefaultRequestHandler = class {
     if (!pushNotificationConfig.id) {
       pushNotificationConfig.id = taskId;
     }
-    const configs = this.pushNotificationConfigs.get(taskId) || [];
-    const updatedConfigs = configs.filter((c) => c.id !== pushNotificationConfig.id);
-    updatedConfigs.push(pushNotificationConfig);
-    this.pushNotificationConfigs.set(taskId, updatedConfigs);
+    await this.pushNotificationStore?.save(taskId, pushNotificationConfig);
     return params;
   }
   async getTaskPushNotificationConfig(params) {
@@ -636,7 +738,7 @@ var DefaultRequestHandler = class {
     if (!task) {
       throw A2AError.taskNotFound(params.id);
     }
-    const configs = this.pushNotificationConfigs.get(params.id) || [];
+    const configs = await this.pushNotificationStore?.load(params.id) || [];
     if (configs.length === 0) {
       throw A2AError.internalError(`Push notification config not found for task ${params.id}.`);
     }
@@ -660,7 +762,7 @@ var DefaultRequestHandler = class {
     if (!task) {
       throw A2AError.taskNotFound(params.id);
     }
-    const configs = this.pushNotificationConfigs.get(params.id) || [];
+    const configs = await this.pushNotificationStore?.load(params.id) || [];
     return configs.map((config) => ({
       taskId: params.id,
       pushNotificationConfig: config
@@ -675,16 +777,7 @@ var DefaultRequestHandler = class {
       throw A2AError.taskNotFound(params.id);
     }
     const { id: taskId, pushNotificationConfigId } = params;
-    const configs = this.pushNotificationConfigs.get(taskId);
-    if (!configs) {
-      return;
-    }
-    const updatedConfigs = configs.filter((c) => c.id !== pushNotificationConfigId);
-    if (updatedConfigs.length === 0) {
-      this.pushNotificationConfigs.delete(taskId);
-    } else if (updatedConfigs.length < configs.length) {
-      this.pushNotificationConfigs.set(taskId, updatedConfigs);
-    }
+    await this.pushNotificationStore?.delete(taskId, pushNotificationConfigId);
   }
   async *resubscribe(params) {
     if (!this.agentCard.capabilities.streaming) {
@@ -719,6 +812,28 @@ var DefaultRequestHandler = class {
       eventQueue.stop();
     }
   }
+  async _sendPushNotificationIfNeeded(event) {
+    if (!this.agentCard.capabilities.pushNotifications) {
+      return;
+    }
+    let taskId = "";
+    if (event.kind == "task") {
+      const task2 = event;
+      taskId = task2.id;
+    } else {
+      taskId = event.taskId;
+    }
+    if (!taskId) {
+      console.error(`Task ID not found for event ${event.kind}.`);
+      return;
+    }
+    const task = await this.taskStore.load(taskId);
+    if (!task) {
+      console.error(`Task ${taskId} not found.`);
+      return;
+    }
+    this.pushNotificationSender?.send(task);
+  }
 };
 
 // src/server/store.ts
@@ -859,8 +974,10 @@ var JsonRpcTransportHandler = class {
   A2AError,
   DefaultExecutionEventBus,
   DefaultExecutionEventBusManager,
+  DefaultPushNotificationSender,
   DefaultRequestHandler,
   ExecutionEventQueue,
+  InMemoryPushNotificationStore,
   InMemoryTaskStore,
   JsonRpcTransportHandler,
   RequestContext,

package/dist/server/index.d.cts

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'events';
-import { B as Message, aw as Task, aO as TaskStatusUpdateEvent, aQ as TaskArtifactUpdateEvent, ac as AgentCard, w as MessageSendParams, V as TaskQueryParams, X as TaskIdParams, Z as TaskPushNotificationConfig, a1 as GetTaskPushNotificationConfigParams, a5 as ListTaskPushNotificationConfigParams, a7 as DeleteTaskPushNotificationConfigParams, i as JSONRPCResponse, au as JSONRPCError } from '../types-DNKcmF0f.cjs';
+import { B as Message, aw as Task, aO as TaskStatusUpdateEvent, aQ as TaskArtifactUpdateEvent, y as PushNotificationConfig, ac as AgentCard, w as MessageSendParams, V as TaskQueryParams, X as TaskIdParams, Z as TaskPushNotificationConfig, a1 as GetTaskPushNotificationConfigParams, a5 as ListTaskPushNotificationConfigParams, a7 as DeleteTaskPushNotificationConfigParams, i as JSONRPCResponse, au as JSONRPCError } from '../types-DNKcmF0f.cjs';
 import { A as A2ARequestHandler } from '../a2a_request_handler-DUvKWfix.cjs';
 
 type AgentExecutionEvent = Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent;
@@ -119,14 +119,31 @@ declare class InMemoryTaskStore implements TaskStore {
     save(task: Task): Promise<void>;
 }
 
+interface PushNotificationStore {
+    save(taskId: string, pushNotificationConfig: PushNotificationConfig): Promise<void>;
+    load(taskId: string): Promise<PushNotificationConfig[]>;
+    delete(taskId: string, configId?: string): Promise<void>;
+}
+declare class InMemoryPushNotificationStore implements PushNotificationStore {
+    private store;
+    save(taskId: string, pushNotificationConfig: PushNotificationConfig): Promise<void>;
+    load(taskId: string): Promise<PushNotificationConfig[]>;
+    delete(taskId: string, configId?: string): Promise<void>;
+}
+
+interface PushNotificationSender {
+    send(task: Task): Promise<void>;
+}
+
 declare class DefaultRequestHandler implements A2ARequestHandler {
     private readonly agentCard;
     private readonly extendedAgentCard?;
     private readonly taskStore;
     private readonly agentExecutor;
     private readonly eventBusManager;
-    private readonly pushNotificationConfigs;
-    constructor(agentCard: AgentCard, taskStore: TaskStore, agentExecutor: AgentExecutor, eventBusManager?: ExecutionEventBusManager, extendedAgentCard?: AgentCard);
+    private readonly pushNotificationStore?;
+    private readonly pushNotificationSender?;
+    constructor(agentCard: AgentCard, taskStore: TaskStore, agentExecutor: AgentExecutor, eventBusManager?: ExecutionEventBusManager, pushNotificationStore?: PushNotificationStore, pushNotificationSender?: PushNotificationSender, extendedAgentCard?: AgentCard);
     getAgentCard(): Promise<AgentCard>;
     getAuthenticatedExtendedAgentCard(): Promise<AgentCard>;
     private _createRequestContext;
@@ -140,6 +157,7 @@ declare class DefaultRequestHandler implements A2ARequestHandler {
     listTaskPushNotificationConfigs(params: ListTaskPushNotificationConfigParams): Promise<TaskPushNotificationConfig[]>;
     deleteTaskPushNotificationConfig(params: DeleteTaskPushNotificationConfigParams): Promise<void>;
     resubscribe(params: TaskIdParams): AsyncGenerator<Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent, void, undefined>;
+    private _sendPushNotificationIfNeeded;
 }
 
 declare class ResultManager {
@@ -207,4 +225,22 @@ declare class A2AError extends Error {
     static authenticatedExtendedCardNotConfigured(): A2AError;
 }
 
-export { A2AError, A2ARequestHandler, type AgentExecutionEvent, type AgentExecutor, DefaultExecutionEventBus, DefaultExecutionEventBusManager, DefaultRequestHandler, type ExecutionEventBus, type ExecutionEventBusManager, ExecutionEventQueue, InMemoryTaskStore, JsonRpcTransportHandler, RequestContext, ResultManager, type TaskStore };
+interface DefaultPushNotificationSenderOptions {
+    /**
+     * Timeout in milliseconds for the abort controller. Defaults to 5000ms.
+     */
+    timeout?: number;
+    /**
+     * Custom header name for the token. Defaults to 'X-A2A-Notification-Token'.
+     */
+    tokenHeaderName?: string;
+}
+declare class DefaultPushNotificationSender implements PushNotificationSender {
+    private readonly pushNotificationStore;
+    private readonly options;
+    constructor(pushNotificationStore: PushNotificationStore, options?: DefaultPushNotificationSenderOptions);
+    send(task: Task): Promise<void>;
+    private _dispatchNotification;
+}
+
+export { A2AError, A2ARequestHandler, type AgentExecutionEvent, type AgentExecutor, DefaultExecutionEventBus, DefaultExecutionEventBusManager, DefaultPushNotificationSender, type DefaultPushNotificationSenderOptions, DefaultRequestHandler, type ExecutionEventBus, type ExecutionEventBusManager, ExecutionEventQueue, InMemoryPushNotificationStore, InMemoryTaskStore, JsonRpcTransportHandler, type PushNotificationSender, type PushNotificationStore, RequestContext, ResultManager, type TaskStore };

package/dist/server/index.d.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'events';
-import { B as Message, aw as Task, aO as TaskStatusUpdateEvent, aQ as TaskArtifactUpdateEvent, ac as AgentCard, w as MessageSendParams, V as TaskQueryParams, X as TaskIdParams, Z as TaskPushNotificationConfig, a1 as GetTaskPushNotificationConfigParams, a5 as ListTaskPushNotificationConfigParams, a7 as DeleteTaskPushNotificationConfigParams, i as JSONRPCResponse, au as JSONRPCError } from '../types-DNKcmF0f.js';
+import { B as Message, aw as Task, aO as TaskStatusUpdateEvent, aQ as TaskArtifactUpdateEvent, y as PushNotificationConfig, ac as AgentCard, w as MessageSendParams, V as TaskQueryParams, X as TaskIdParams, Z as TaskPushNotificationConfig, a1 as GetTaskPushNotificationConfigParams, a5 as ListTaskPushNotificationConfigParams, a7 as DeleteTaskPushNotificationConfigParams, i as JSONRPCResponse, au as JSONRPCError } from '../types-DNKcmF0f.js';
 import { A as A2ARequestHandler } from '../a2a_request_handler-B5t-IxgA.js';
 
 type AgentExecutionEvent = Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent;
@@ -119,14 +119,31 @@ declare class InMemoryTaskStore implements TaskStore {
     save(task: Task): Promise<void>;
 }
 
+interface PushNotificationStore {
+    save(taskId: string, pushNotificationConfig: PushNotificationConfig): Promise<void>;
+    load(taskId: string): Promise<PushNotificationConfig[]>;
+    delete(taskId: string, configId?: string): Promise<void>;
+}
+declare class InMemoryPushNotificationStore implements PushNotificationStore {
+    private store;
+    save(taskId: string, pushNotificationConfig: PushNotificationConfig): Promise<void>;
+    load(taskId: string): Promise<PushNotificationConfig[]>;
+    delete(taskId: string, configId?: string): Promise<void>;
+}
+
+interface PushNotificationSender {
+    send(task: Task): Promise<void>;
+}
+
 declare class DefaultRequestHandler implements A2ARequestHandler {
     private readonly agentCard;
     private readonly extendedAgentCard?;
     private readonly taskStore;
     private readonly agentExecutor;
     private readonly eventBusManager;
-    private readonly pushNotificationConfigs;
-    constructor(agentCard: AgentCard, taskStore: TaskStore, agentExecutor: AgentExecutor, eventBusManager?: ExecutionEventBusManager, extendedAgentCard?: AgentCard);
+    private readonly pushNotificationStore?;
+    private readonly pushNotificationSender?;
+    constructor(agentCard: AgentCard, taskStore: TaskStore, agentExecutor: AgentExecutor, eventBusManager?: ExecutionEventBusManager, pushNotificationStore?: PushNotificationStore, pushNotificationSender?: PushNotificationSender, extendedAgentCard?: AgentCard);
     getAgentCard(): Promise<AgentCard>;
     getAuthenticatedExtendedAgentCard(): Promise<AgentCard>;
     private _createRequestContext;
@@ -140,6 +157,7 @@ declare class DefaultRequestHandler implements A2ARequestHandler {
     listTaskPushNotificationConfigs(params: ListTaskPushNotificationConfigParams): Promise<TaskPushNotificationConfig[]>;
     deleteTaskPushNotificationConfig(params: DeleteTaskPushNotificationConfigParams): Promise<void>;
     resubscribe(params: TaskIdParams): AsyncGenerator<Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent, void, undefined>;
+    private _sendPushNotificationIfNeeded;
 }
 
 declare class ResultManager {
@@ -207,4 +225,22 @@ declare class A2AError extends Error {
     static authenticatedExtendedCardNotConfigured(): A2AError;
 }
 
-export { A2AError, A2ARequestHandler, type AgentExecutionEvent, type AgentExecutor, DefaultExecutionEventBus, DefaultExecutionEventBusManager, DefaultRequestHandler, type ExecutionEventBus, type ExecutionEventBusManager, ExecutionEventQueue, InMemoryTaskStore, JsonRpcTransportHandler, RequestContext, ResultManager, type TaskStore };
+interface DefaultPushNotificationSenderOptions {
+    /**
+     * Timeout in milliseconds for the abort controller. Defaults to 5000ms.
+     */
+    timeout?: number;
+    /**
+     * Custom header name for the token. Defaults to 'X-A2A-Notification-Token'.
+     */
+    tokenHeaderName?: string;
+}
+declare class DefaultPushNotificationSender implements PushNotificationSender {
+    private readonly pushNotificationStore;
+    private readonly options;
+    constructor(pushNotificationStore: PushNotificationStore, options?: DefaultPushNotificationSenderOptions);
+    send(task: Task): Promise<void>;
+    private _dispatchNotification;
+}
+
+export { A2AError, A2ARequestHandler, type AgentExecutionEvent, type AgentExecutor, DefaultExecutionEventBus, DefaultExecutionEventBusManager, DefaultPushNotificationSender, type DefaultPushNotificationSenderOptions, DefaultRequestHandler, type ExecutionEventBus, type ExecutionEventBusManager, ExecutionEventQueue, InMemoryPushNotificationStore, InMemoryTaskStore, JsonRpcTransportHandler, type PushNotificationSender, type PushNotificationStore, RequestContext, ResultManager, type TaskStore };

package/dist/server/index.js

@@ -257,6 +257,97 @@ var ResultManager = class {
   }
 };
 
+// src/server/push_notification/push_notification_store.ts
+var InMemoryPushNotificationStore = class {
+  store = /* @__PURE__ */ new Map();
+  async save(taskId, pushNotificationConfig) {
+    const configs = this.store.get(taskId) || [];
+    if (!pushNotificationConfig.id) {
+      pushNotificationConfig.id = taskId;
+    }
+    const existingIndex = configs.findIndex((config) => config.id === pushNotificationConfig.id);
+    if (existingIndex !== -1) {
+      configs.splice(existingIndex, 1);
+    }
+    configs.push(pushNotificationConfig);
+    this.store.set(taskId, configs);
+  }
+  async load(taskId) {
+    const configs = this.store.get(taskId);
+    return configs || [];
+  }
+  async delete(taskId, configId) {
+    if (configId === void 0) {
+      configId = taskId;
+    }
+    const configs = this.store.get(taskId);
+    if (!configs) {
+      return;
+    }
+    const configIndex = configs.findIndex((config) => config.id === configId);
+    if (configIndex !== -1) {
+      configs.splice(configIndex, 1);
+    }
+    if (configs.length === 0) {
+      this.store.delete(taskId);
+    } else {
+      this.store.set(taskId, configs);
+    }
+  }
+};
+
+// src/server/push_notification/default_push_notification_sender.ts
+var DefaultPushNotificationSender = class {
+  pushNotificationStore;
+  options;
+  constructor(pushNotificationStore, options = {}) {
+    this.pushNotificationStore = pushNotificationStore;
+    this.options = {
+      timeout: 5e3,
+      tokenHeaderName: "X-A2A-Notification-Token",
+      ...options
+    };
+  }
+  async send(task) {
+    const pushConfigs = await this.pushNotificationStore.load(task.id);
+    if (!pushConfigs || pushConfigs.length === 0) {
+      return;
+    }
+    pushConfigs.forEach((pushConfig) => {
+      this._dispatchNotification(task, pushConfig).catch((error) => {
+        console.error(`Error sending push notification for task_id=${task.id} to URL: ${pushConfig.url}. Error:`, error);
+      });
+    });
+  }
+  async _dispatchNotification(task, pushConfig) {
+    const url = pushConfig.url;
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.options.timeout);
+    try {
+      const headers = {
+        "Content-Type": "application/json"
+      };
+      if (pushConfig.token) {
+        headers[this.options.tokenHeaderName] = pushConfig.token;
+      }
+      const response = await fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(task),
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+      console.info(`Push notification sent for task_id=${task.id} to URL: ${url}`);
+    } catch (error) {
+      console.error(`Error sending push notification for task_id=${task.id} to URL: ${url}. Error:`, error);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+};
+
 // src/server/request_handler/default_request_handler.ts
 var terminalStates = ["completed", "failed", "canceled", "rejected"];
 var DefaultRequestHandler = class {
@@ -265,14 +356,18 @@ var DefaultRequestHandler = class {
   taskStore;
   agentExecutor;
   eventBusManager;
-  // Store for push notification configurations (could be part of TaskStore or separate)
-  pushNotificationConfigs = /* @__PURE__ */ new Map();
-  constructor(agentCard, taskStore, agentExecutor, eventBusManager = new DefaultExecutionEventBusManager(), extendedAgentCard) {
+  pushNotificationStore;
+  pushNotificationSender;
+  constructor(agentCard, taskStore, agentExecutor, eventBusManager = new DefaultExecutionEventBusManager(), pushNotificationStore, pushNotificationSender, extendedAgentCard) {
     this.agentCard = agentCard;
     this.taskStore = taskStore;
     this.agentExecutor = agentExecutor;
     this.eventBusManager = eventBusManager;
     this.extendedAgentCard = extendedAgentCard;
+    if (agentCard.capabilities.pushNotifications) {
+      this.pushNotificationStore = pushNotificationStore || new InMemoryPushNotificationStore();
+      this.pushNotificationSender = pushNotificationSender || new DefaultPushNotificationSender(this.pushNotificationStore);
+    }
   }
   async getAgentCard() {
     return this.agentCard;
@@ -324,6 +419,7 @@ var DefaultRequestHandler = class {
     try {
       for await (const event of eventQueue.events()) {
         await resultManager.processEvent(event);
+        await this._sendPushNotificationIfNeeded(event);
         if (options?.firstResultResolver && !firstResultSent) {
           if (event.kind === "message" || event.kind === "task") {
             options.firstResultResolver(event);
@@ -355,6 +451,9 @@ var DefaultRequestHandler = class {
     resultManager.setContext(incomingMessage);
     const requestContext = await this._createRequestContext(incomingMessage, taskId, false);
     const finalMessageForAgent = requestContext.userMessage;
+    if (params.configuration?.pushNotificationConfig && this.agentCard.capabilities.pushNotifications) {
+      await this.pushNotificationStore?.save(taskId, params.configuration.pushNotificationConfig);
+    }
     const eventBus = this.eventBusManager.createOrGetByTaskId(taskId);
     const eventQueue = new ExecutionEventQueue(eventBus);
     this.agentExecutor.execute(requestContext, eventBus).catch((err) => {
@@ -422,6 +521,9 @@ var DefaultRequestHandler = class {
     const finalMessageForAgent = requestContext.userMessage;
     const eventBus = this.eventBusManager.createOrGetByTaskId(taskId);
     const eventQueue = new ExecutionEventQueue(eventBus);
+    if (params.configuration?.pushNotificationConfig && this.agentCard.capabilities.pushNotifications) {
+      await this.pushNotificationStore?.save(taskId, params.configuration.pushNotificationConfig);
+    }
     this.agentExecutor.execute(requestContext, eventBus).catch((err) => {
       console.error(`Agent execution failed for stream message ${finalMessageForAgent.messageId}:`, err);
       const errorTaskStatus = {
@@ -449,6 +551,7 @@ var DefaultRequestHandler = class {
     try {
       for await (const event of eventQueue.events()) {
         await resultManager.processEvent(event);
+        await this._sendPushNotificationIfNeeded(event);
         yield event;
       }
     } finally {
@@ -513,10 +616,7 @@ var DefaultRequestHandler = class {
     if (!pushNotificationConfig.id) {
       pushNotificationConfig.id = taskId;
     }
-    const configs = this.pushNotificationConfigs.get(taskId) || [];
-    const updatedConfigs = configs.filter((c) => c.id !== pushNotificationConfig.id);
-    updatedConfigs.push(pushNotificationConfig);
-    this.pushNotificationConfigs.set(taskId, updatedConfigs);
+    await this.pushNotificationStore?.save(taskId, pushNotificationConfig);
     return params;
   }
   async getTaskPushNotificationConfig(params) {
@@ -527,7 +627,7 @@ var DefaultRequestHandler = class {
     if (!task) {
       throw A2AError.taskNotFound(params.id);
     }
-    const configs = this.pushNotificationConfigs.get(params.id) || [];
+    const configs = await this.pushNotificationStore?.load(params.id) || [];
     if (configs.length === 0) {
       throw A2AError.internalError(`Push notification config not found for task ${params.id}.`);
     }
@@ -551,7 +651,7 @@ var DefaultRequestHandler = class {
     if (!task) {
       throw A2AError.taskNotFound(params.id);
     }
-    const configs = this.pushNotificationConfigs.get(params.id) || [];
+    const configs = await this.pushNotificationStore?.load(params.id) || [];
     return configs.map((config) => ({
       taskId: params.id,
       pushNotificationConfig: config
@@ -566,16 +666,7 @@ var DefaultRequestHandler = class {
       throw A2AError.taskNotFound(params.id);
     }
     const { id: taskId, pushNotificationConfigId } = params;
-    const configs = this.pushNotificationConfigs.get(taskId);
-    if (!configs) {
-      return;
-    }
-    const updatedConfigs = configs.filter((c) => c.id !== pushNotificationConfigId);
-    if (updatedConfigs.length === 0) {
-      this.pushNotificationConfigs.delete(taskId);
-    } else if (updatedConfigs.length < configs.length) {
-      this.pushNotificationConfigs.set(taskId, updatedConfigs);
-    }
+    await this.pushNotificationStore?.delete(taskId, pushNotificationConfigId);
   }
   async *resubscribe(params) {
     if (!this.agentCard.capabilities.streaming) {
@@ -610,6 +701,28 @@ var DefaultRequestHandler = class {
       eventQueue.stop();
     }
   }
+  async _sendPushNotificationIfNeeded(event) {
+    if (!this.agentCard.capabilities.pushNotifications) {
+      return;
+    }
+    let taskId = "";
+    if (event.kind == "task") {
+      const task2 = event;
+      taskId = task2.id;
+    } else {
+      taskId = event.taskId;
+    }
+    if (!taskId) {
+      console.error(`Task ID not found for event ${event.kind}.`);
+      return;
+    }
+    const task = await this.taskStore.load(taskId);
+    if (!task) {
+      console.error(`Task ${taskId} not found.`);
+      return;
+    }
+    this.pushNotificationSender?.send(task);
+  }
 };
 
 // src/server/store.ts
@@ -627,8 +740,10 @@ export {
   A2AError,
   DefaultExecutionEventBus,
   DefaultExecutionEventBusManager,
+  DefaultPushNotificationSender,
   DefaultRequestHandler,
   ExecutionEventQueue,
+  InMemoryPushNotificationStore,
   InMemoryTaskStore,
   JsonRpcTransportHandler,
   RequestContext,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a2a-js/sdk",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Server & Client SDK for Agent2Agent protocol",
   "repository": {
     "type": "git",