feat: Production-Grade: Persistent Store & Distributed Event Bus

package.json

@@ -24,6 +24,9 @@
       "server/grpc": [
         "./dist/server/grpc/index.d.ts"
       ],
+      "server/distributed": [
+        "./dist/server/distributed/index.d.ts"
+      ],
       "client": [
         "./dist/client/index.d.ts"
       ],
@@ -53,6 +56,11 @@
       "import": "./dist/server/grpc/index.js",
       "require": "./dist/server/grpc/index.cjs"
     },
+    "./server/distributed": {
+      "types": "./dist/server/distributed/index.d.ts",
+      "import": "./dist/server/distributed/index.js",
+      "require": "./dist/server/distributed/index.cjs"
+    },
     "./client": {
       "types": "./dist/client/index.d.ts",
       "import": "./dist/client/index.js",
@@ -70,6 +78,10 @@
     "README.md"
   ],
   "devDependencies": {
+    "@aws-sdk/client-dynamodb": "^3.596.0",
+    "@aws-sdk/client-sns": "^3.596.0",
+    "@aws-sdk/client-sqs": "^3.596.0",
+    "@aws-sdk/lib-dynamodb": "^3.596.0",
     "@betterer/cli": "^6.0.0-alpha.1",
     "@betterer/typescript": "^6.0.0-alpha.1",
     "@bufbuild/buf": "^1.61.0",
@@ -81,6 +93,8 @@
     "@types/node": "^22.13.14",
     "@types/supertest": "^6.0.3",
     "@vitest/coverage-v8": "^3.2.4",
+    "aws-sdk-client-mock": "^4.1.0",
+    "aws-sdk-client-mock-vitest": "^7.0.1",
     "esbuild": "^0.27.0",
     "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",
@@ -110,11 +124,27 @@
     "uuid": "^11.1.0"
   },
   "peerDependencies": {
+    "@aws-sdk/client-dynamodb": "^3.596.0",
+    "@aws-sdk/client-sns": "^3.596.0",
+    "@aws-sdk/client-sqs": "^3.596.0",
+    "@aws-sdk/lib-dynamodb": "^3.596.0",
     "@bufbuild/protobuf": "^2.10.2",
     "@grpc/grpc-js": "^1.11.0",
     "express": "^4.21.2 || ^5.1.0"
   },
   "peerDependenciesMeta": {
+    "@aws-sdk/client-dynamodb": {
+      "optional": true
+    },
+    "@aws-sdk/client-sns": {
+      "optional": true
+    },
+    "@aws-sdk/client-sqs": {
+      "optional": true
+    },
+    "@aws-sdk/lib-dynamodb": {
+      "optional": true
+    },
     "express": {
       "optional": true
     },

src/server/distributed/index.ts

@@ -0,0 +1,73 @@
+/**
+ * @a2a-js/sdk/server/distributed
+ *
+ * Drop-in replacements for the default in-process components when deploying
+ * the A2A server across multiple instances (ECS Fargate, Kubernetes, etc.).
+ *
+ * This sub-path is intentionally kept separate from `@a2a-js/sdk/server` so
+ * that single-instance deployments incur zero AWS SDK dependency weight.
+ * Install the peer dependencies only when you use this sub-path:
+ *
+ * ```bash
+ * npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb \
+ *             @aws-sdk/client-sns @aws-sdk/client-sqs
+ * ```
+ *
+ * Typical wiring:
+ *
+ * ```typescript
+ * import {
+ *   DynamoDBTaskStore,
+ *   QueueLifecycleManager,
+ *   SnsEventBusManager,
+ * } from '@a2a-js/sdk/server/distributed';
+ *
+ * const lifecycle = new QueueLifecycleManager({ snsTopicArn, sqsClient, snsClient });
+ * const { queueUrl, instanceId } = await lifecycle.provision();
+ *
+ * const eventBusManager = new SnsEventBusManager({
+ *   snsTopicArn, sqsQueueUrl: queueUrl, instanceId, snsClient, sqsClient,
+ * });
+ * eventBusManager.start();
+ *
+ * const requestHandler = new DefaultRequestHandler(
+ *   agentCard,
+ *   new DynamoDBTaskStore({ client: dynamoDocClient, tableName }),
+ *   executor,
+ *   eventBusManager,
+ * );
+ * ```
+ *
+ * @module @a2a-js/sdk/server/distributed
+ */
+
+// ── Persistent task store (DynamoDB) ─────────────────────────────────────────
+
+export { DynamoDBTaskStore } from '../store/dynamo_task_store.js';
+export type { DynamoTaskStoreConfig } from '../store/dynamo_task_store.js';
+
+// Typed error hierarchy — callers can catch by class and inspect `.retryable`
+// to decide whether to surface the error or transparently retry upstream.
+export {
+  TaskStoreError,
+  TaskNotFoundError,
+  TaskConflictError,
+  StoreUnavailableError,
+} from '../store/errors.js';
+
+// ── Per-instance queue lifecycle (SQS + SNS subscription) ────────────────────
+
+export { QueueLifecycleManager } from '../events/queue_lifecycle_manager.js';
+export type {
+  QueueLifecycleConfig,
+  QueueProvisionResult,
+} from '../events/queue_lifecycle_manager.js';
+
+// ── Distributed event bus manager (SNS fan-out → SQS per-instance delivery) ──
+
+export {
+  SnsEventBusManager,
+  DistributedExecutionEventBus,
+  SqsEventPoller,
+} from '../events/sns_sqs_event_bus_manager.js';
+export type { SnsEventBusConfig } from '../events/sns_sqs_event_bus_manager.js';