v0.2.0: OAuth2, Postgres, telemetry, health, rate limiting, push notifications, CLI

.changeset/v0_2_0-auth.md

@@ -0,0 +1,5 @@
+---
+"@reaatech/a2a-reference-auth": minor
+---
+
+Add `OAuth2Strategy`: token validation plus client-credentials, authorization-code (with PKCE), and refresh grants. Cache the JWKS for the strategy lifetime, accept the `Bearer` scheme case-insensitively (RFC 6749), and add a shared scope-extraction helper.

.changeset/v0_2_0-cli.md

@@ -0,0 +1,5 @@
+---
+"@reaatech/a2a-reference-cli": minor
+---
+
+New package: the `a2a` scaffolding CLI generates an Express or Hono A2A agent with optional API-key/JWT auth and MCP bridge integration.

.changeset/v0_2_0-core.md

@@ -0,0 +1,9 @@
+---
+"@reaatech/a2a-reference-core": minor
+---
+
+Spec-compliant Agent Card signatures and security schemes.
+
+- **Breaking:** Agent Card signatures now use the A2A spec JWS shape (`protected`/`signature`/`header`) — a JWS over the RFC 8785 (JCS) canonicalization of the card. Verification runs on `jose` (WebCrypto, edge-compatible) and supports RS/PS/ES 256/384/512 and EdDSA/Ed25519; keys are supplied directly or resolved from the protected header `jku`.
+- **Breaking:** Security schemes now use the spec's OpenAPI-style `type` discriminator (`apiKey` | `http` | `oauth2` | `openIdConnect` | `mutualTLS`) with fully modeled OAuth `flows`, replacing the previous `scheme`/`httpScheme` shape.
+- Add `auth-required` task-state transitions.

.changeset/v0_2_0-observability.md

@@ -0,0 +1,5 @@
+---
+"@reaatech/a2a-reference-observability": minor
+---
+
+Add a pluggable telemetry-provider abstraction (tracer/meter/span with a no-op default) and a dedicated logger module with configurable transport.

.changeset/v0_2_0-persistence.md

@@ -0,0 +1,5 @@
+---
+"@reaatech/a2a-reference-persistence": minor
+---
+
+Add `PostgresTaskStore`. Support principal-scoped `list()` across all stores so `tasks/list` totals and pagination respect the caller. Make `PostgresTaskStore.update()` transactional and persist history/artifacts.

.changeset/v0_2_0-server.md

@@ -0,0 +1,5 @@
+---
+"@reaatech/a2a-reference-server": minor
+---
+
+Add health checks (`/healthz`, `/readyz`), an in-memory rate limiter, push-notification delivery wired into the event bus, a Redis SSE coordinator, extended Agent Card serving, and `tasks/sendSubscribe` over JSON-RPC. Add the `trustProxyHeaders` option controlling whether the rate-limit client IP is read from `X-Forwarded-For` (default off). `Retry-After` and the `retryAfter` body field are reported in seconds.

AGENTS.md

@@ -8,13 +8,14 @@ This is a **pnpm workspace monorepo** managed with Turborepo.
 
 ```
 packages/
-  core/         — Canonical A2A types, Zod schemas, error classes
+  core/         — Canonical A2A types, Zod schemas, error classes, signature verification
   server/       — A2A server framework (Express + Hono adapters)
   client/       — A2A client SDK
-  auth/         — Authentication strategies
-  persistence/  — Task store abstractions
+  auth/         — Authentication strategies (OAuth2, JWT, API key)
+  persistence/  — Task store abstractions (InMemory, Redis, Postgres, FileSystem)
   mcp-bridge/   — A2A ↔ MCP bidirectional adapter
-  observability/ — Logging, tracing, metrics
+  observability/ — Logging, tracing, metrics, telemetry
+  cli/          — Agent scaffolding CLI (a2a init)
 ```
 
 ## Build System
@@ -28,21 +29,14 @@ packages/
 ### Common Commands
 
 ```bash
-# Install all dependencies
-pnpm install
-
-# Build everything
-pnpm build
-
-# Run all tests
-pnpm test
-
-# Lint & format
-pnpm lint
-pnpm lint:fix
-
-# Type-check without emit
-pnpm typecheck
+pnpm install          # Install all dependencies
+pnpm build            # Build everything
+pnpm test             # Run all tests
+pnpm test:coverage    # Run tests with coverage (>90% required)
+pnpm lint             # Lint & format check
+pnpm lint:fix         # Auto-fix lint issues
+pnpm typecheck        # Type-check without emit
+pnpm docs             # Generate TypeDoc API docs
 ```
 
 ## Coding Conventions
@@ -53,19 +47,19 @@ pnpm typecheck
 4. **Types:** Prefer `type` over `interface` for data shapes. Keep `interface` for class contracts.
 5. **No `any`:** Biome is configured to error on `any`. Use `unknown` + narrowing instead.
 6. **Exports:** Always provide ESM + CJS dual output with `types` condition first in `exports`.
+7. **Coverage:** All packages must maintain >90% statement coverage.
 
 ## Adding a New Package
 
 1. Create `packages/<name>/` with `package.json`, `tsconfig.json`, `src/index.ts`
 2. Use `@reaatech/a2a-reference-core` for shared types. Do not duplicate schemas.
-3. Add to `pnpm-workspace.yaml` if not under `packages/*`
-4. Run `pnpm install` from the package directory
+3. Run `pnpm install` from the package directory
 
 ## Testing
 
 - Unit tests live next to source files: `src/foo.test.ts`
 - E2E tests live in `e2e/`
-- Always run `pnpm test` before committing
+- Always run `pnpm test` and verify `pnpm test:coverage` before committing
 
 ## Protocol Compliance
 

ARCHITECTURE.md

@@ -4,66 +4,73 @@
 
 ## Overview
 
-This monorepo implements Google's Agent-to-Agent (A2A) protocol in TypeScript with an enterprise-grade A2A↔MCP bridge adapter.
+This monorepo implements Google's Agent-to-Agent (A2A) protocol in TypeScript with an enterprise-grade A2A↔MCP bridge adapter, CLI scaffolding, and production infrastructure.
 
 ## Package Boundaries
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│                        A2A Server                           │
+│                      A2A Server (Express + Hono)             │
 │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
-│  │  Express    │  │    Hono     │  │   AgentExecutor     │  │
-│  │  Adapter    │  │   Adapter   │  │   (user logic)      │  │
+│  │ Agent Card  │  │   JSON-RPC  │  │   AgentExecutor     │  │
+│  │  / Health   │  │  / SSE / PN │  │   (user logic)      │  │
 │  └─────────────┘  └─────────────┘  └─────────────────────┘  │
 └─────────────────────────────────────────────────────────────┘
-                              │
-                              ▼
-┌─────────────────────────────────────────────────────────────┐
-│                      A2A Client SDK                         │
-│         (discovery, task lifecycle, streaming)              │
-└─────────────────────────────────────────────────────────────┘
-                              │
-              ┌───────────────┼───────────────┐
-              ▼               ▼               ▼
-        ┌─────────┐    ┌──────────┐    ┌──────────┐
-        │  Auth   │    │Persistence│   │Observability│
-        └─────────┘    └──────────┘    └──────────┘
-                              │
-                              ▼
+       │           │           │
+       ▼           ▼           ▼
+┌─────────┐ ┌──────────┐ ┌──────────┐
+│  Auth    │ │Persistence│ │Observability│
+│ OAuth2   │ │InMemory   │ │ Pino     │
+│ JWT      │ │Redis      │ │ OTel     │
+│ API Key  │ │Postgres   │ │ Metrics  │
+│          │ │FileSystem │ │          │
+└─────────┘ └──────────┘ └──────────┘
+       │
+       ▼
 ┌─────────────────────────────────────────────────────────────┐
 │                    A2A ↔ MCP Bridge                         │
-│           (bidirectional protocol adapter)                  │
+│   McpToolAdapter (A2A→MCP) + A2aAsMcpServer (MCP→A2A)      │
 └─────────────────────────────────────────────────────────────┘
 ```
 
 ## Data Flow
 
 ### Sync Task (JSON-RPC)
-
 ```
 Client ──POST /──► Server ──► AgentExecutor ──► TaskStore
                      │                            │
                      └──────JSON-RPC Response◄────┘
 ```
 
 ### Streaming Task (SSE)
-
 ```
-Client ──POST /──► Server ──► AgentExecutor
+Client ──POST /tasks/sendSubscribe ──► Server ──► AgentExecutor
                      │
-                     ├──► SSE: TaskStatusUpdateEvent
-                     ├──► SSE: TaskArtifactUpdateEvent
-                     └──► SSE: TaskStatusUpdateEvent (completed)
+                     ├──► SSE: TaskStatusUpdateEvent (working)
+                     ├──► SSE: TaskArtifactUpdateEvent (artifact data)
+                     └──► SSE: TaskStatusUpdateEvent (completed/failed)
 ```
 
-### Bridge: A2A → MCP
-
+### Push Notifications
 ```
-A2A Task ──► BridgeAgent ──► tools/list ──► MCP Server
-                │
-                ├──► Map skills ◄── tools schema
+Agent ──► PushNotificationManager ──► HTTP POST ──► Client Webhook
                 │
-                └──► tools/call ──► MCP Server ──► Result ──► A2A Artifact
+                ├──► Bearer token auth header
+                └──► Retry with exponential backoff (3 attempts)
+```
+
+### Rate Limiting
+```
+Request ──► RateLimiter.check() ──► allowed? ──► 200 (with X-RateLimit-Remaining)
+                                      │
+                                      └──► denied? ──► 429 (with Retry-After)
+```
+
+## Health Checks
+```
+GET /healthz ──► createHealthStatus() ──► Check task store
+                  │                         ├── Custom health checks
+                  └──► JSON: { status: "ok", checks: [...] }
 ```
 
 ## State Machine
@@ -74,29 +81,30 @@ A2A Task ──► BridgeAgent ──► tools/list ──► MCP Server
          │          └────┬─────┘         │
          │               │               │
          │               ▼               │
-         │          ┌─────────┐         │
-         │    ┌────►│ working │────┐    │
-         │    │     └────┬────┘    │    │
-         │    │          │         │    │
-         │    │          ▼         │    │
-         │    │   ┌─────────────┐  │    │
-         │    └───│ input-required│──┘    │
+         │          ┌─────────┐          │
+         │    ┌────►│ working │────┐     │
+         │    │     └────┬────┘    │     │
+         │    │          │         │     │
+         │    │          ▼         │     │
+         │    │   ┌─────────────┐  │     │
+         │    └───│input-required│──┘     │
          │        └──────┬──────┘         │
          │               │                │
+         │          ┌────▼─────┐          │
+         │          │auth-required        │
+         │          └────┬─────┘          │
+         │               │                │
          │               ▼                │
          │      ┌─────────────────┐      │
-         └──────│ completed/failed │──────┘
-                │  /canceled/rejected │
+         └──────│ completed/failed│──────┘
+                │ /canceled/rejected │
                 └─────────────────┘
 ```
 
-## Technology Choices
-
-See [DEV_PLAN.md](./DEV_PLAN.md) Section 2.2 for the full technology stack rationale.
-
 ## Extension Points
 
-- **AuthStrategy** — implement custom auth schemes
-- **TaskStore** — add new persistence backends
-- **AgentExecutor** — implement agent logic
-- **TransportAdapter** — add new HTTP frameworks
+- **AuthStrategy** — implement custom auth schemes (OAuth2, JWT, API key)
+- **TaskStore** — add new persistence backends (InMemory, Redis, Postgres, FileSystem)
+- **AgentExecutor** — implement agent business logic
+- **TelemetryProvider** — plug in OpenTelemetry or custom observability
+- **RateLimiter** — custom key functions and window strategies