@a2a-js/sdk 0.3.4 → 0.3.5

package/README.md

@@ -163,19 +163,22 @@ class TaskExecutor implements AgentExecutor {
     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);
+    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 = {
@@ -281,6 +284,28 @@ const client = await A2AClient.fromCardUrl(
 await client.sendMessage({ message: { messageId: uuidv4(), role: "user", parts: [{ kind: "text", text: "A message requiring custom headers." }], kind: "message" } });
 ```
 
+### Example: Specifying a Timeout
+
+This example creates a `fetch` wrapper that sets a timeout for every outgoing request.
+
+```typescript
+import { A2AClient } from "@a2a-js/sdk/client";
+
+// 1. Create a wrapper around the global fetch function.
+const fetchWithTimeout: typeof fetch = async (url, init) => {
+  return fetch(url, { ...init, signal: AbortSignal.timeout(5000)});
+};
+
+// 2. Provide the custom fetch implementation to the client.
+const client = await A2AClient.fromCardUrl(
+  "http://localhost:4000/.well-known/agent-card.json",
+  { fetchImpl: fetchWithTimeout }
+);
+
+// Now, all requests made by this client instance will have a configured timeout.
+await client.sendMessage({ message: { messageId: uuidv4(), role: "user", parts: [{ kind: "text", text: "A message requiring custom headers." }], kind: "message" } });
+```
+
 ### 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).
@@ -354,15 +379,22 @@ class StreamingExecutor implements AgentExecutor {
     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() },
-    });
+    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({

package/dist/{chunk-JA52GYRU.js → chunk-SY3G7ITG.js}

@@ -100,10 +100,8 @@ var JsonRpcTransportHandler = class {
       } else {
         throw A2AError.parseError("Invalid request body type.");
       }
-      if (rpcRequest.jsonrpc !== "2.0" || !rpcRequest.method || typeof rpcRequest.method !== "string") {
-        throw A2AError.invalidRequest(
-          "Invalid JSON-RPC request structure."
-        );
+      if (!this.isRequestValid(rpcRequest)) {
+        throw A2AError.invalidRequest("Invalid JSON-RPC Request.");
       }
     } catch (error) {
       const a2aError = error instanceof A2AError ? error : A2AError.parseError(error.message || "Failed to parse JSON request.");
@@ -123,8 +121,8 @@ var JsonRpcTransportHandler = class {
           result
         };
       }
-      if (!rpcRequest.params) {
-        throw A2AError.invalidParams(`'params' is required for '${method}'`);
+      if (!this.paramsAreValid(rpcRequest.params)) {
+        throw A2AError.invalidParams(`Invalid method parameters.`);
       }
       if (method === "message/stream" || method === "tasks/resubscribe") {
         const params = rpcRequest.params;
@@ -199,6 +197,37 @@ var JsonRpcTransportHandler = class {
       };
     }
   }
+  // Validates the basic structure of a JSON-RPC request
+  isRequestValid(rpcRequest) {
+    if (rpcRequest.jsonrpc !== "2.0") {
+      return false;
+    }
+    if ("id" in rpcRequest) {
+      const id = rpcRequest.id;
+      const isString = typeof id === "string";
+      const isInteger = typeof id === "number" && Number.isInteger(id);
+      const isNull = id === null;
+      if (!isString && !isInteger && !isNull) {
+        return false;
+      }
+    }
+    if (!rpcRequest.method || typeof rpcRequest.method !== "string") {
+      return false;
+    }
+    return true;
+  }
+  // Validates that params is an object with non-empty string keys
+  paramsAreValid(params) {
+    if (typeof params !== "object" || params === null || Array.isArray(params)) {
+      return false;
+    }
+    for (const key of Object.keys(params)) {
+      if (key === "") {
+        return false;
+      }
+    }
+    return true;
+  }
 };
 
 export {

package/dist/server/express/index.cjs

@@ -138,10 +138,8 @@ var JsonRpcTransportHandler = class {
       } else {
         throw A2AError.parseError("Invalid request body type.");
       }
-      if (rpcRequest.jsonrpc !== "2.0" || !rpcRequest.method || typeof rpcRequest.method !== "string") {
-        throw A2AError.invalidRequest(
-          "Invalid JSON-RPC request structure."
-        );
+      if (!this.isRequestValid(rpcRequest)) {
+        throw A2AError.invalidRequest("Invalid JSON-RPC Request.");
       }
     } catch (error) {
       const a2aError = error instanceof A2AError ? error : A2AError.parseError(error.message || "Failed to parse JSON request.");
@@ -161,8 +159,8 @@ var JsonRpcTransportHandler = class {
           result
         };
       }
-      if (!rpcRequest.params) {
-        throw A2AError.invalidParams(`'params' is required for '${method}'`);
+      if (!this.paramsAreValid(rpcRequest.params)) {
+        throw A2AError.invalidParams(`Invalid method parameters.`);
       }
       if (method === "message/stream" || method === "tasks/resubscribe") {
         const params = rpcRequest.params;
@@ -237,6 +235,37 @@ var JsonRpcTransportHandler = class {
       };
     }
   }
+  // Validates the basic structure of a JSON-RPC request
+  isRequestValid(rpcRequest) {
+    if (rpcRequest.jsonrpc !== "2.0") {
+      return false;
+    }
+    if ("id" in rpcRequest) {
+      const id = rpcRequest.id;
+      const isString = typeof id === "string";
+      const isInteger = typeof id === "number" && Number.isInteger(id);
+      const isNull = id === null;
+      if (!isString && !isInteger && !isNull) {
+        return false;
+      }
+    }
+    if (!rpcRequest.method || typeof rpcRequest.method !== "string") {
+      return false;
+    }
+    return true;
+  }
+  // Validates that params is an object with non-empty string keys
+  paramsAreValid(params) {
+    if (typeof params !== "object" || params === null || Array.isArray(params)) {
+      return false;
+    }
+    for (const key of Object.keys(params)) {
+      if (key === "") {
+        return false;
+      }
+    }
+    return true;
+  }
 };
 
 // src/constants.ts
@@ -256,12 +285,24 @@ var A2AExpressApp = class {
    * @param app Optional existing Express app.
    * @param baseUrl The base URL for A2A endpoints (e.g., "/a2a/api").
    * @param middlewares Optional array of Express middlewares to apply to the A2A routes.
-   * @param agentCardPath Optional custom path for the agent card endpoint (defaults to /.well-known/agent-card.json).
+   * @param agentCardPath Optional custom path for the agent card endpoint (defaults to .well-known/agent-card.json).
    * @returns The Express app with A2A routes.
    */
   setupRoutes(app, baseUrl = "", middlewares, agentCardPath = AGENT_CARD_PATH) {
     const router = import_express.default.Router();
     router.use(import_express.default.json(), ...middlewares ?? []);
+    router.use((err, req, res, next) => {
+      if (err instanceof SyntaxError && "body" in err) {
+        const a2aError = A2AError.parseError("Invalid JSON payload.");
+        const errorResponse = {
+          jsonrpc: "2.0",
+          id: null,
+          error: a2aError.toJSONRPCError()
+        };
+        return res.status(400).json(errorResponse);
+      }
+      next(err);
+    });
     router.get(`/${agentCardPath}`, async (req, res) => {
       try {
         const agentCard = await this.requestHandler.getAgentCard();

package/dist/server/express/index.d.cts

@@ -11,7 +11,7 @@ declare class A2AExpressApp {
      * @param app Optional existing Express app.
      * @param baseUrl The base URL for A2A endpoints (e.g., "/a2a/api").
      * @param middlewares Optional array of Express middlewares to apply to the A2A routes.
-     * @param agentCardPath Optional custom path for the agent card endpoint (defaults to /.well-known/agent-card.json).
+     * @param agentCardPath Optional custom path for the agent card endpoint (defaults to .well-known/agent-card.json).
      * @returns The Express app with A2A routes.
      */
     setupRoutes(app: Express, baseUrl?: string, middlewares?: Array<RequestHandler | ErrorRequestHandler>, agentCardPath?: string): Express;

package/dist/server/express/index.d.ts

@@ -11,7 +11,7 @@ declare class A2AExpressApp {
      * @param app Optional existing Express app.
      * @param baseUrl The base URL for A2A endpoints (e.g., "/a2a/api").
      * @param middlewares Optional array of Express middlewares to apply to the A2A routes.
-     * @param agentCardPath Optional custom path for the agent card endpoint (defaults to /.well-known/agent-card.json).
+     * @param agentCardPath Optional custom path for the agent card endpoint (defaults to .well-known/agent-card.json).
      * @returns The Express app with A2A routes.
      */
     setupRoutes(app: Express, baseUrl?: string, middlewares?: Array<RequestHandler | ErrorRequestHandler>, agentCardPath?: string): Express;

package/dist/server/express/index.js

@@ -4,7 +4,7 @@ import {
 import {
   A2AError,
   JsonRpcTransportHandler
-} from "../../chunk-JA52GYRU.js";
+} from "../../chunk-SY3G7ITG.js";
 
 // src/server/express/a2a_express_app.ts
 import express from "express";
@@ -21,12 +21,24 @@ var A2AExpressApp = class {
    * @param app Optional existing Express app.
    * @param baseUrl The base URL for A2A endpoints (e.g., "/a2a/api").
    * @param middlewares Optional array of Express middlewares to apply to the A2A routes.
-   * @param agentCardPath Optional custom path for the agent card endpoint (defaults to /.well-known/agent-card.json).
+   * @param agentCardPath Optional custom path for the agent card endpoint (defaults to .well-known/agent-card.json).
    * @returns The Express app with A2A routes.
    */
   setupRoutes(app, baseUrl = "", middlewares, agentCardPath = AGENT_CARD_PATH) {
     const router = express.Router();
     router.use(express.json(), ...middlewares ?? []);
+    router.use((err, req, res, next) => {
+      if (err instanceof SyntaxError && "body" in err) {
+        const a2aError = A2AError.parseError("Invalid JSON payload.");
+        const errorResponse = {
+          jsonrpc: "2.0",
+          id: null,
+          error: a2aError.toJSONRPCError()
+        };
+        return res.status(400).json(errorResponse);
+      }
+      next(err);
+    });
     router.get(`/${agentCardPath}`, async (req, res) => {
       try {
         const agentCard = await this.requestHandler.getAgentCard();

package/dist/server/index.cjs

@@ -410,9 +410,11 @@ var InMemoryPushNotificationStore = class {
 // src/server/push_notification/default_push_notification_sender.ts
 var DefaultPushNotificationSender = class {
   pushNotificationStore;
+  notificationChain;
   options;
   constructor(pushNotificationStore, options = {}) {
     this.pushNotificationStore = pushNotificationStore;
+    this.notificationChain = /* @__PURE__ */ new Map();
     this.options = {
       timeout: 5e3,
       tokenHeaderName: "X-A2A-Notification-Token",
@@ -424,10 +426,22 @@ var DefaultPushNotificationSender = class {
     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);
+    const lastPromise = this.notificationChain.get(task.id) ?? Promise.resolve();
+    const newPromise = lastPromise.then(async () => {
+      const dispatches = pushConfigs.map(async (pushConfig) => {
+        try {
+          await this._dispatchNotification(task, pushConfig);
+        } catch (error) {
+          console.error(`Error sending push notification for task_id=${task.id} to URL: ${pushConfig.url}. Error:`, error);
+        }
       });
+      await Promise.all(dispatches);
+    });
+    this.notificationChain.set(task.id, newPromise);
+    newPromise.finally(() => {
+      if (this.notificationChain.get(task.id) === newPromise) {
+        this.notificationChain.delete(task.id);
+      }
     });
   }
   async _dispatchNotification(task, pushConfig) {
@@ -451,8 +465,6 @@ var DefaultPushNotificationSender = class {
         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);
     }
@@ -500,6 +512,8 @@ var DefaultRequestHandler = class {
       if (terminalStates.includes(task.status.state)) {
         throw A2AError.invalidRequest(`Task ${task.id} is in a terminal state (${task.status.state}) and cannot be modified.`);
       }
+      task.history = [...task.history || [], incomingMessage];
+      await this.taskStore.save(task);
     }
     if (incomingMessage.referenceTaskIds && incomingMessage.referenceTaskIds.length > 0) {
       referenceTasks = [];
@@ -532,8 +546,14 @@ var DefaultRequestHandler = class {
         await resultManager.processEvent(event);
         await this._sendPushNotificationIfNeeded(event);
         if (options?.firstResultResolver && !firstResultSent) {
-          if (event.kind === "message" || event.kind === "task") {
-            options.firstResultResolver(event);
+          let firstResult;
+          if (event.kind === "message") {
+            firstResult = event;
+          } else {
+            firstResult = resultManager.getCurrentTask();
+          }
+          if (firstResult) {
+            options.firstResultResolver(firstResult);
             firstResultSent = true;
           }
         }
@@ -694,7 +714,9 @@ var DefaultRequestHandler = class {
     }
     const eventBus = this.eventBusManager.getByTaskId(params.id);
     if (eventBus) {
+      const eventQueue = new ExecutionEventQueue(eventBus);
       await this.agentExecutor.cancelTask(params.id, eventBus);
+      await this._processEvents(params.id, new ResultManager(this.taskStore), eventQueue);
     } else {
       task.status = {
         state: "canceled",
@@ -713,6 +735,12 @@ var DefaultRequestHandler = class {
       await this.taskStore.save(task);
     }
     const latestTask = await this.taskStore.load(params.id);
+    if (!latestTask) {
+      throw A2AError.internalError(`Task ${params.id} not found after cancellation.`);
+    }
+    if (latestTask.status.state != "canceled") {
+      throw A2AError.taskNotCancelable(params.id);
+    }
     return latestTask;
   }
   async setTaskPushNotificationConfig(params) {
@@ -869,10 +897,8 @@ var JsonRpcTransportHandler = class {
       } else {
         throw A2AError.parseError("Invalid request body type.");
       }
-      if (rpcRequest.jsonrpc !== "2.0" || !rpcRequest.method || typeof rpcRequest.method !== "string") {
-        throw A2AError.invalidRequest(
-          "Invalid JSON-RPC request structure."
-        );
+      if (!this.isRequestValid(rpcRequest)) {
+        throw A2AError.invalidRequest("Invalid JSON-RPC Request.");
       }
     } catch (error) {
       const a2aError = error instanceof A2AError ? error : A2AError.parseError(error.message || "Failed to parse JSON request.");
@@ -892,8 +918,8 @@ var JsonRpcTransportHandler = class {
           result
         };
       }
-      if (!rpcRequest.params) {
-        throw A2AError.invalidParams(`'params' is required for '${method}'`);
+      if (!this.paramsAreValid(rpcRequest.params)) {
+        throw A2AError.invalidParams(`Invalid method parameters.`);
       }
       if (method === "message/stream" || method === "tasks/resubscribe") {
         const params = rpcRequest.params;
@@ -968,6 +994,37 @@ var JsonRpcTransportHandler = class {
       };
     }
   }
+  // Validates the basic structure of a JSON-RPC request
+  isRequestValid(rpcRequest) {
+    if (rpcRequest.jsonrpc !== "2.0") {
+      return false;
+    }
+    if ("id" in rpcRequest) {
+      const id = rpcRequest.id;
+      const isString = typeof id === "string";
+      const isInteger = typeof id === "number" && Number.isInteger(id);
+      const isNull = id === null;
+      if (!isString && !isInteger && !isNull) {
+        return false;
+      }
+    }
+    if (!rpcRequest.method || typeof rpcRequest.method !== "string") {
+      return false;
+    }
+    return true;
+  }
+  // Validates that params is an object with non-empty string keys
+  paramsAreValid(params) {
+    if (typeof params !== "object" || params === null || Array.isArray(params)) {
+      return false;
+    }
+    for (const key of Object.keys(params)) {
+      if (key === "") {
+        return false;
+      }
+    }
+    return true;
+  }
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/server/index.d.cts

@@ -199,6 +199,8 @@ declare class JsonRpcTransportHandler {
      * For non-streaming methods, it returns a Promise of a single JSONRPCMessage (Result or ErrorResponse).
      */
     handle(requestBody: any): Promise<JSONRPCResponse | AsyncGenerator<JSONRPCResponse, void, undefined>>;
+    private isRequestValid;
+    private paramsAreValid;
 }
 
 /**
@@ -237,6 +239,7 @@ interface DefaultPushNotificationSenderOptions {
 }
 declare class DefaultPushNotificationSender implements PushNotificationSender {
     private readonly pushNotificationStore;
+    private notificationChain;
     private readonly options;
     constructor(pushNotificationStore: PushNotificationStore, options?: DefaultPushNotificationSenderOptions);
     send(task: Task): Promise<void>;

package/dist/server/index.d.ts

@@ -199,6 +199,8 @@ declare class JsonRpcTransportHandler {
      * For non-streaming methods, it returns a Promise of a single JSONRPCMessage (Result or ErrorResponse).
      */
     handle(requestBody: any): Promise<JSONRPCResponse | AsyncGenerator<JSONRPCResponse, void, undefined>>;
+    private isRequestValid;
+    private paramsAreValid;
 }
 
 /**
@@ -237,6 +239,7 @@ interface DefaultPushNotificationSenderOptions {
 }
 declare class DefaultPushNotificationSender implements PushNotificationSender {
     private readonly pushNotificationStore;
+    private notificationChain;
     private readonly options;
     constructor(pushNotificationStore: PushNotificationStore, options?: DefaultPushNotificationSenderOptions);
     send(task: Task): Promise<void>;

package/dist/server/index.js

@@ -1,7 +1,7 @@
 import {
   A2AError,
   JsonRpcTransportHandler
-} from "../chunk-JA52GYRU.js";
+} from "../chunk-SY3G7ITG.js";
 
 // src/server/agent_execution/request_context.ts
 var RequestContext = class {
@@ -299,9 +299,11 @@ var InMemoryPushNotificationStore = class {
 // src/server/push_notification/default_push_notification_sender.ts
 var DefaultPushNotificationSender = class {
   pushNotificationStore;
+  notificationChain;
   options;
   constructor(pushNotificationStore, options = {}) {
     this.pushNotificationStore = pushNotificationStore;
+    this.notificationChain = /* @__PURE__ */ new Map();
     this.options = {
       timeout: 5e3,
       tokenHeaderName: "X-A2A-Notification-Token",
@@ -313,10 +315,22 @@ var DefaultPushNotificationSender = class {
     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);
+    const lastPromise = this.notificationChain.get(task.id) ?? Promise.resolve();
+    const newPromise = lastPromise.then(async () => {
+      const dispatches = pushConfigs.map(async (pushConfig) => {
+        try {
+          await this._dispatchNotification(task, pushConfig);
+        } catch (error) {
+          console.error(`Error sending push notification for task_id=${task.id} to URL: ${pushConfig.url}. Error:`, error);
+        }
       });
+      await Promise.all(dispatches);
+    });
+    this.notificationChain.set(task.id, newPromise);
+    newPromise.finally(() => {
+      if (this.notificationChain.get(task.id) === newPromise) {
+        this.notificationChain.delete(task.id);
+      }
     });
   }
   async _dispatchNotification(task, pushConfig) {
@@ -340,8 +354,6 @@ var DefaultPushNotificationSender = class {
         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);
     }
@@ -389,6 +401,8 @@ var DefaultRequestHandler = class {
       if (terminalStates.includes(task.status.state)) {
         throw A2AError.invalidRequest(`Task ${task.id} is in a terminal state (${task.status.state}) and cannot be modified.`);
       }
+      task.history = [...task.history || [], incomingMessage];
+      await this.taskStore.save(task);
     }
     if (incomingMessage.referenceTaskIds && incomingMessage.referenceTaskIds.length > 0) {
       referenceTasks = [];
@@ -421,8 +435,14 @@ var DefaultRequestHandler = class {
         await resultManager.processEvent(event);
         await this._sendPushNotificationIfNeeded(event);
         if (options?.firstResultResolver && !firstResultSent) {
-          if (event.kind === "message" || event.kind === "task") {
-            options.firstResultResolver(event);
+          let firstResult;
+          if (event.kind === "message") {
+            firstResult = event;
+          } else {
+            firstResult = resultManager.getCurrentTask();
+          }
+          if (firstResult) {
+            options.firstResultResolver(firstResult);
             firstResultSent = true;
           }
         }
@@ -583,7 +603,9 @@ var DefaultRequestHandler = class {
     }
     const eventBus = this.eventBusManager.getByTaskId(params.id);
     if (eventBus) {
+      const eventQueue = new ExecutionEventQueue(eventBus);
       await this.agentExecutor.cancelTask(params.id, eventBus);
+      await this._processEvents(params.id, new ResultManager(this.taskStore), eventQueue);
     } else {
       task.status = {
         state: "canceled",
@@ -602,6 +624,12 @@ var DefaultRequestHandler = class {
       await this.taskStore.save(task);
     }
     const latestTask = await this.taskStore.load(params.id);
+    if (!latestTask) {
+      throw A2AError.internalError(`Task ${params.id} not found after cancellation.`);
+    }
+    if (latestTask.status.state != "canceled") {
+      throw A2AError.taskNotCancelable(params.id);
+    }
     return latestTask;
   }
   async setTaskPushNotificationConfig(params) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a2a-js/sdk",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Server & Client SDK for Agent2Agent protocol",
   "repository": {
     "type": "git",
@@ -47,6 +47,7 @@
     "@types/mocha": "^10.0.10",
     "@types/node": "^22.13.14",
     "@types/sinon": "^17.0.4",
+    "@types/supertest": "^6.0.3",
     "c8": "^10.1.3",
     "chai": "^5.2.0",
     "express": "^5.1.0",
@@ -55,6 +56,7 @@
     "json-schema-to-typescript": "^15.0.4",
     "mocha": "^11.6.0",
     "sinon": "^20.0.0",
+    "supertest": "^7.1.4",
     "tsup": "^8.5.0",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2"
@@ -66,8 +68,9 @@
     "test": "mocha test/**/*.spec.ts",
     "coverage": "c8 npm run test",
     "generate": "curl https://raw.githubusercontent.com/google-a2a/A2A/refs/heads/main/specification/json/a2a.json > spec.json && node scripts/generateTypes.js && rm spec.json",
-    "sample:cli": "tsx src/samples/cli.ts",
-    "sample:movie-agent": "tsx src/samples/agents/movie-agent/index.ts"
+    "a2a:cli": "tsx src/samples/cli.ts",
+    "agents:movie-agent": "tsx src/samples/agents/movie-agent/index.ts",
+    "agents:sample-agent": "tsx src/samples/agents/sample-agent/index.ts"
   },
   "dependencies": {
     "uuid": "^11.1.0"
@@ -83,4 +86,4 @@
   "mocha": {
     "require": "tsx"
   }
-}
+}