From 35583306cff041707be179dd2a5bcc76fad4c0bf Mon Sep 17 00:00:00 2001
From: Darrel Miller <darrel.miller@microsoft.com>
Date: Fri, 30 Jan 2026 10:10:01 -0500
Subject: [PATCH 01/12] feat(docs): Add comprehensive overview for A2A Protocol
 v1.0 release

---
 docs/whats-new-v1.md | 920 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 920 insertions(+)
 create mode 100644 docs/whats-new-v1.md

diff --git a/docs/whats-new-v1.md b/docs/whats-new-v1.md
new file mode 100644
index 000000000..553ae78a5
--- /dev/null
+++ b/docs/whats-new-v1.md
@@ -0,0 +1,920 @@
+# What's New in A2A Protocol v1.0
+
+This document provides a comprehensive overview of changes from A2A Protocol v0.3.0 to v1.0. The v1.0 release represents a significant maturation of the protocol with enhanced clarity, stronger specifications, and important structural improvements.
+
+## Overview of Major Themes
+
+The v1.0 release focuses on four major themes:
+
+### 1. **Protocol Maturity and Standardization**
+
+- Migration to formal specification standards (RFC 9457, RFC 8785, RFC 7515)
+- Stricter adherence to industry-standard patterns for REST, gRPC, and JSON-RPC bindings
+- Enhanced versioning strategy with explicit backward compatibility rules
+- Comprehensive error taxonomy with protocol-specific mappings
+
+### 2. **Enhanced Type Safety and Clarity**
+
+- Removal of discriminator `kind` fields in favor of JSON member-based polymorphism
+- **Breaking:** Enum values changed from `PascalCase` to `SCREAMING_SNAKE_CASE` for consistency
+- Stricter field naming conventions (camelCase for JSON)
+- More precise timestamp specifications (ISO 8601 with millisecond precision)
+- Better-defined data types with clearer Optional vs Required semantics
+
+### 3. **Improved Developer Experience**
+
+- Renamed operations for consistency and clarity
+- Reorganized Agent Card structure for better logical grouping
+- Enhanced extension mechanism with versioning and requirement declarations
+- More explicit service parameter handling (A2A-Version, A2A-Extensions headers)
+
+### 4. **Enterprise-Ready Features**
+
+- Agent Card signature verification using JWS and JSON Canonicalization
+- Formal specification of all three protocol bindings with equivalence guarantees
+- Enhanced security scheme declarations with mutual TLS support
+- Cursor-based pagination for scalable task listing
+
+---
+
+## Behavioral Changes for Core Operations
+
+### Send Message (`message/send` → **SendMessage**)
+
+**v0.3.0 Behavior:**
+
+- Operation named `message/send`
+- Blocking behavior not explicitly controllable
+- Less formal specification of when Task vs Message is returned
+
+**v1.0 Changes:**
+
+- **✅ NEW:** Operation formally named **SendMessage** (with legacy alias support)
+- **✅ NEW:** `SendMessageConfiguration.blocking` parameter explicitly controls wait behavior
+    - `blocking: true` - Server waits until task reaches terminal or interrupted state
+    - `blocking: false` - Server returns immediately; client polls/streams for updates
+- **✅ CLARIFIED:** More precise specification of Task vs Message return semantics
+    - Simple queries MAY return Message directly without creating a Task
+    - Complex operations MUST return Task for asynchronous handling
+- **✅ NEW:** Service parameters transmitted as headers/metadata:
+    - `A2A-Version`: Protocol version (Major.Minor format)
+    - `A2A-Extensions`: Comma-separated extension URIs
+
+### Send Streaming Message (`message/stream` → **SendStreamingMessage**)
+
+**v0.3.0 Behavior:**
+
+- Operation named `message/stream`
+- SSE-based streaming for JSON-RPC, unspecified for gRPC
+- Stream events had `kind` discriminator field
+
+**v1.0 Changes:**
+
+- **✅ RENAMED:** Operation now **SendStreamingMessage**
+- **✅ BREAKING:** Stream events no longer have `kind` field
+    - Use JSON member names to discriminate between TaskStatusUpdateEvent and TaskArtifactUpdateEvent
+- **✅ NEW:** Formal gRPC streaming semantics defined
+- **✅ REMOVED:** `final` boolean field removed from TaskStatusUpdateEvent. Leverage protocol binding specific stream closure mechanism instead.
+- **✅ CLARIFIED:** Multiple concurrent streams allowed; all receive same ordered events
+- **✅ NEW:** Blocking parameter applies but streaming always provides real-time updates
+
+### Get Task (`tasks/get` → **GetTask**)
+
+**v0.3.0 Behavior:**
+
+- Operation named `tasks/get`
+- Returns task with status, artifacts, and optionally history
+- Less formal specification of what "include history" means
+
+**v1.0 Changes:**
+
+- **✅ RENAMED:** Operation now **GetTask**
+- **✅ NEW:** `createdAt` and `lastModified` timestamp fields added to Task object
+- **✅ CLARIFIED:** More precise specification of history inclusion behavior
+- **✅ NEW:** Task object now includes `extensions[]` array in messages and artifacts
+- **✅ CLARIFIED:** Authentication/authorization scoping - servers MUST only return tasks visible to caller
+
+### List Tasks (`tasks/list` → **ListTasks**)
+
+**v0.3.0 Behavior:**
+
+- Operation named `tasks/list`
+- Available in gRPC and REST only
+- Basic pagination with page numbers
+
+**v1.0 Changes:**
+
+- **✅ RENAMED:** Operation now **ListTasks**
+- **✅ BREAKING:** Changed to cursor-based pagination for scalability
+    - Request: `cursor` (opaque token from previous response), `limit` (max results)
+    - Response: `tasks[]`, `nextCursor` (for next page)
+- **✅ NEW:** Enhanced filtering capabilities with more explicit specifications
+- **✅ CLARIFIED:** Task visibility scoped to authenticated caller
+
+### Cancel Task (`tasks/cancel` → **CancelTask**)
+
+**v0.3.0 Behavior:**
+
+- Operation named `tasks/cancel`
+- Request with taskId, returns Task
+- Error if task not cancelable (implicit)
+
+**v1.0 Changes:**
+
+- **✅ RENAMED:** Operation now **CancelTask**
+- **✅ NEW:** Explicit `TaskNotCancelableError` for terminal/non-cancelable tasks
+- **✅ CLARIFIED:** More precise specification of when cancellation is allowed
+- **✅ CLARIFIED:** Task state transitions for cancellation scenarios
+
+### Get Agent Card (Well-known URI and **GetExtendedAgentCard**)
+
+**v0.3.0 Behavior:**
+
+- Discovery via `/.well-known/agent-card.json`
+- Extended card via `agent/getAuthenticatedExtendedCard`
+- `supportsAuthenticatedExtendedCard` boolean at top level
+
+**v1.0 Changes:**
+
+- **✅ RENAMED:** `agent/getAuthenticatedExtendedCard` → **GetExtendedAgentCard**
+- **✅ BREAKING:** `supportsAuthenticatedExtendedCard` moved to `capabilities.extendedAgentCard`
+- **✅ NEW:** Agent Card signature support with JWS (RFC 7515) and canonicalization (RFC 8785)
+- **✅ NEW:** `agentId` field added to identify agent instances
+- **✅ BREAKING:** `protocolVersion` moved from AgentCard to individual AgentInterface objects
+- **✅ BREAKING:** `preferredTransport` and `additionalInterfaces` consolidated into `supportedInterfaces[]`
+    - Each interface has `url`, `protocolBinding`, and `protocolVersion`
+- **✅ NEW:** Extension declarations now include `uri`, `description`, and `required` flag
+- **✅ NEW:** Mutual TLS security scheme support added
+
+### NEW: Subscribe to Task (**SubscribeToTask**)
+
+**v0.3.0 Behavior:**
+
+- Used `tasks/resubscribe` to reconnect interrupted SSE streams
+- Backfill behavior implementation-dependent
+
+**v1.0 Changes:**
+
+- **✅ NEW OPERATION:** **SubscribeToTask** replaces informal resubscription
+- **✅ CLARIFIED:** Formal specification of streaming subscription lifecycle
+- **✅ CLARIFIED:** Stream closure behavior when task reaches terminal state
+- **✅ CLARIFIED:** Multiple concurrent subscriptions supported per task
+- **✅ BEHAVIOURCHANGE:** Can subscribe to tasks not originally created via streaming
+
+### Push Notification Operations
+
+**v0.3.0 Operations:**
+
+- `tasks/pushNotificationConfig/set`
+- `tasks/pushNotificationConfig/get`
+- `tasks/pushNotificationConfig/list`
+- `tasks/pushNotificationConfig/delete`
+
+**v1.0 Changes:**
+
+- **✅ RENAMED:** Operations now **CreatePushNotificationConfig**, **GetPushNotificationConfig**, **ListPushNotificationConfigs**, **DeletePushNotificationConfig**
+- **✅ NEW:** `createdAt` timestamp field added to PushNotificationConfig
+- **✅ BREAKING:** `token` field removed from PushNotificationConfig (authentication handled via schemes)
+- **✅ NEW:** `configId` field added for unique identification
+- **✅ CLARIFIED:** Push notification payloads now use StreamResponse format
+- **✅ NEW:** Explicit `PushNotificationNotSupportedError` when capability not available
+
+---
+
+## Structural Changes in Core Model Objects
+
+### Task Object
+
+**Added Fields:**
+
+- ✅ `createdAt`: Timestamp (ISO 8601) - Task creation time
+- ✅ `lastModified`: Timestamp (ISO 8601) - Last state change time
+
+**Modified Fields:**
+
+- ✅ `status`: TaskStatus object now includes more precise timestamp semantics
+
+**Removed Fields:**
+
+- ⛔ `kind`: Discriminator field removed (was always "task")
+
+**Behavior Changes:**
+
+- Messages in `history[]` now include `extensions[]` array
+- Artifacts now include `extensions[]` array and `metadata` map
+
+### TaskStatus Object
+
+**Added Fields:**
+
+- No new top-level fields
+
+**Modified Fields:**
+
+- ✅ `state`: **BREAKING** - Enum values changed from lowercase/kebab-case to `SCREAMING_SNAKE_CASE` with `TASK_STATE_` prefix
+    - v0.3.0: `"submitted"`, `"working"`, `"completed"`, `"failed"`, `"cancelled"`, `"rejected"`, `"input-required"`, `"auth-required"`
+    - v1.0: `"TASK_STATE_SUBMITTED"`, `"TASK_STATE_WORKING"`, `"TASK_STATE_COMPLETED"`, `"TASK_STATE_FAILED"`, `"TASK_STATE_CANCELED"`, `"TASK_STATE_REJECTED"`, `"TASK_STATE_INPUT_REQUIRED"`, `"TASK_STATE_AUTH_REQUIRED"`
+- ✅ `timestamp`: Now explicitly ISO 8601 UTC with millisecond precision (YYYY-MM-DDTHH:mm:ss.sssZ)
+- ✅ `message`: Optional Message with enhanced extension support
+
+**Removed Fields:**
+
+- None
+
+**Example Migration:**
+
+```json
+// v0.3.0
+{
+  "status": {
+    "state": "completed",
+    "timestamp": "2024-03-15T10:15:00Z"
+  }
+}
+
+// v1.0
+{
+  "status": {
+    "state": "TASK_STATE_COMPLETED",
+    "timestamp": "2024-03-15T10:15:00.000Z"
+  }
+}
+```
+
+### Message Object
+
+**Added Fields:**
+
+- ✅ `timestamp`: ISO 8601 timestamp - Message creation time
+- ✅ `extensions[]`: Array of extension URIs applicable to this message
+
+**Modified Fields:**
+
+- ✅ `role`: **BREAKING** - Enum values changed from lowercase to `SCREAMING_SNAKE_CASE` with `ROLE_` prefix
+    - v0.3.0: `"user"`, `"agent"`
+    - v1.0: `"ROLE_USER"`, `"ROLE_AGENT"`
+- ✅ `metadata`: Remains optional key-value map but with stricter typing
+
+**Removed Fields:**
+
+- None
+
+**Example Migration:**
+
+```json
+// v0.3.0
+{
+  "role": "user",
+  "parts": [{"kind": "text", "text": "Hello"}]
+}
+
+// v1.0
+{
+  "role": "ROLE_USER",
+  "parts": [{"text": "Hello"}],
+  "timestamp": "2024-03-15T10:15:00.000Z"
+}
+```
+
+**Behavior Changes:**
+
+- Parts array now uses member-based discrimination instead of `kind` field
+
+### Part Object
+
+**BREAKING CHANGE - Complete Redesign:**
+
+The Part structure has been completely redesigned in v1.0. Instead of separate TextPart, FilePart, and DataPart message types, there is now a single unified `Part` message.
+
+**v0.3.0 Structure (Separate Types):**
+
+```json
+// Text example
+{
+  "kind": "text",
+  "text": "Hello world"
+}
+
+// File example
+{
+  "kind": "file",
+  "file": {
+    "fileWithUri": "https://example.com/doc.pdf",
+    "mimeType": "application/pdf"
+  }
+}
+
+// Data example
+{
+  "kind": "data",
+  "data": {"key": "value"}
+}
+```
+
+**v1.0 Structure (Unified Part):**
+
+```json
+// Text example
+{
+  "text": "Hello world",
+  "mediaType": "text/plain"
+}
+
+// File with URL example
+{
+  "url": "https://example.com/doc.pdf",
+  "filename": "doc.pdf",
+  "mediaType": "application/pdf"
+}
+
+// File with raw bytes example
+{
+  "raw": "base64encodedcontent==",
+  "filename": "image.png",
+  "mediaType": "image/png"
+}
+
+// Data example
+{
+  "data": {"key": "value"},
+  "mediaType": "application/json"
+}
+```
+
+**Changes:**
+
+- ⛔ **REMOVED:** Separate `TextPart`, `FilePart`, and `DataPart` types
+- ⛔ **REMOVED:** `kind` discriminator field
+- ⛔ **REMOVED:** Nested `file` object structure
+- ✅ **NEW:** Single unified `Part` message with `oneof content` field
+- ✅ **NEW:** Content type determined by which field is present: `text`, `raw`, `url`, or `data`
+- ✅ **NEW:** `mediaType` field (replaces `mimeType`) - available for all part types
+- ✅ **NEW:** `filename` field - available for all part types (not just files)
+- ✅ **NEW:** `raw` field for inline binary content (base64 in JSON)
+- ✅ **NEW:** `url` field for file references (replaces `file.fileWithUri`)
+- ✅ **RETAINED:** `metadata` optional map
+
+**Migration Examples:**
+
+```typescript
+// v0.3.0
+const textPart = { kind: "text", text: "Hello" };
+const filePart = { kind: "file", file: { fileWithUri: "https://...", mimeType: "image/png" } };
+const dataPart = { kind: "data", data: { key: "value" } };
+
+// v1.0
+const textPart = { text: "Hello", mediaType: "text/plain" };
+const filePart = { url: "https://...", mediaType: "image/png", filename: "image.png" };
+const dataPart = { data: { key: "value" }, mediaType: "application/json" };
+
+// Discrimination changed from kind field to member presence
+if (part.kind === "text") { ... }  // v0.3.0
+if ("text" in part) { ... }         // v1.0
+```
+
+### Artifact Object
+
+**Added Fields:**
+
+- ✅ `createdAt`: Timestamp - Artifact creation time
+- ✅ `extensions[]`: Array of extension URIs
+
+**Modified Fields:**
+
+- ✅ `parts[]`: Now uses member-based Part discrimination (see Part changes above)
+
+**Removed Fields:**
+
+- None
+
+**Behavior Changes:**
+
+- Metadata now more formally specified with extension integration
+
+### AgentCard Object
+
+**Added Fields:**
+
+- ✅ `agentId`: Unique identifier for the agent instance
+- ✅ `supportedInterfaces[]`: Array of AgentInterface objects (each with url, protocolBinding, and protocolVersion)
+- ✅ `signatures[]`: Array of JWS signatures for card verification
+
+**Modified Fields:**
+
+- ✅ `capabilities.extendedAgentCard`: Moved from top-level `supportsAuthenticatedExtendedCard`
+- ✅ `extensions[]`: Enhanced with `uri`, `description`, and `required` fields (previously simpler Extension type)
+- ✅ `securitySchemes`: Enhanced with mutual TLS support
+
+**Removed Fields:**
+
+- ⛔ `protocolVersion`: Removed from AgentCard (now in each AgentInterface)
+- ⛔ `preferredTransport`: Consolidated into `supportedInterfaces`
+- ⛔ `additionalInterfaces`: Consolidated into `supportedInterfaces`
+- ⛔ `supportsAuthenticatedExtendedCard`: Moved to `capabilities.extendedAgentCard`
+- ⛔ `url`: Primary endpoint now in `supportedInterfaces[0].url`
+
+**Structure Example:**
+
+**v0.3.0:**
+
+```json
+{
+  "protocolVersion": "0.3",
+  "url": "https://agent.example.com/a2a",
+  "preferredTransport": "JSONRPC",
+  "supportsAuthenticatedExtendedCard": true,
+  "additionalInterfaces": [...]
+}
+```
+
+**v1.0:**
+
+```json
+{
+  "agentId": "agent-abc-123",
+  "supportedInterfaces": [
+    {
+      "url": "https://agent.example.com/a2a",
+      "protocolBinding": "JSONRPC",
+      "protocolVersion": "1.0"
+    }
+  ],
+  "capabilities": {
+    "extendedAgentCard": true
+  },
+  "signatures": [...]
+}
+```
+
+### AgentExtension Object
+
+**v0.3.0 Structure:**
+
+```json
+{
+  "id": "extension-id",
+  "name": "Extension Name",
+  "version": "1.0",
+  "description": "Description",
+  "documentation": "https://...",
+  "metadata": {}
+}
+```
+
+**v1.0 Structure:**
+
+```json
+{
+  "uri": "https://example.com/extensions/custom-ext/v1",
+  "description": "Description",
+  "required": false
+}
+```
+
+**Changes:**
+
+- ⛔ **REMOVED:** `id`, `name`, `version` fields
+- ⛔ **REMOVED:** `documentation` field
+- ⛔ **REMOVED:** `metadata` field
+- ✅ **NEW:** `uri` field - Versioned URI identifying the extension
+- ✅ **NEW:** `required` boolean - Indicates if client must support this extension
+- ✅ **SIMPLIFIED:** Description remains, but structure dramatically simplified
+- ✅ **PATTERN:** Extension versioning now embedded in URI (e.g., `/v1`, `/v2`)
+
+### SecurityScheme Objects
+
+**Added:**
+
+- ✅ `MutualTLSSecurityScheme`: Support for mutual TLS authentication
+
+**Enhanced:**
+
+- ✅ More formal alignment with OpenAPI security scheme patterns
+- ✅ Better documentation of OAuth2 flows and scopes
+- ✅ Clearer distinction between security scheme definitions and requirements
+
+### PushNotificationConfig Object
+
+**Added Fields:**
+
+- ✅ `configId`: Unique identifier for the configuration
+- ✅ `createdAt`: Timestamp - Configuration creation time
+
+**Modified Fields:**
+
+- ✅ `authentication`: Enhanced PushNotificationAuthenticationInfo structure
+
+**Removed Fields:**
+
+- ⛔ `token`: Client-provided token removed (auth handled via schemes)
+
+**Behavior Changes:**
+
+- Configuration now identified by `configId` instead of implicit task association
+- Authentication schemes formalized with proper standards alignment
+
+### Stream Event Objects
+
+**TaskStatusUpdateEvent:**
+
+**v0.3.0:**
+
+```json
+{
+  "kind": "taskStatusUpdate",
+  "taskId": "...",
+  "contextId": "...",
+  "status": {...},
+  "final": true
+}
+```
+
+**v1.0:**
+
+```json
+{
+  "taskStatusUpdate": {
+    "taskId": "...",
+    "contextId": "...",
+    "status": {...}
+  }
+}
+```
+
+**Changes:**
+
+- ⛔ **REMOVED:** `kind` discriminator
+- ⛔ **REMOVED:** `final` boolean field (stream closure indicates completion instead)
+- ✅ **NEW PATTERN:** Event type determined by JSON member name (`taskStatusUpdate` or `taskArtifactUpdate`)
+- ✅ **CLARIFIED:** Terminal state indicated by protocol-specific stream closure mechanism
+
+**TaskArtifactUpdateEvent:**
+
+**v0.3.0:**
+
+```json
+{
+  "kind": "taskArtifactUpdate",
+  "taskId": "...",
+  "contextId": "...",
+  "artifact": {...}
+}
+```
+
+**v1.0:**
+
+```json
+{
+  "taskArtifactUpdate": {
+    "taskId": "...",
+    "contextId": "...",
+    "artifact": {...},
+    "index": 0
+  }
+}
+```
+
+**Changes:**
+
+- ⛔ **REMOVED:** `kind` discriminator
+- ✅ **NEW PATTERN:** Wrapped in `taskArtifactUpdate` object
+- ✅ **NEW:** `index` field indicates artifact position in task's artifacts array
+
+---
+
+## New Dependencies on Other Specifications
+
+v1.0 introduces several new formal dependencies on industry-standard specifications:
+
+### Added Specifications
+
+**✅ RFC 9457 - Problem Details for HTTP APIs**
+
+- **Purpose:** Standardized error response format
+- **Usage:** HTTP+JSON binding error responses
+- **Impact:** More consistent, machine-readable error handling in REST APIs
+
+**✅ RFC 8785 - JSON Canonicalization Scheme (JCS)**
+
+- **Purpose:** Deterministic JSON serialization for signing
+- **Usage:** Agent Card signature verification
+- **Impact:** Enables cryptographic verification of Agent Card integrity
+- **Details:** Canonical form used before JWS signing (excludes `signatures` field)
+
+**✅ RFC 7515 - JSON Web Signature (JWS)**
+
+- **Purpose:** Cryptographic signing standard
+- **Usage:** Agent Card signatures field
+- **Impact:** Industry-standard signature format for trust verification
+- **Details:** Supports detached signatures with public key retrieval via `jku` or trusted keystores
+
+**✅ Google API Design Guidelines**
+
+- **Purpose:** gRPC best practices and conventions
+- **Usage:** gRPC binding design patterns
+- **Impact:** Better alignment with gRPC ecosystem expectations
+
+**✅ ISO 8601**
+
+- **Purpose:** Timestamp format standard
+- **Usage:** All timestamp fields (createdAt, lastModified, timestamp)
+- **Impact:** Explicit format requirement: UTC with millisecond precision (YYYY-MM-DDTHH:mm:ss.sssZ)
+
+### Existing Dependencies (Retained from v0.3.0)
+
+- JSON-RPC 2.0
+- gRPC / Protocol Buffers 3
+- HTTP/HTTPS (various RFCs)
+- Server-Sent Events (SSE) - W3C specification
+- RFC 8615 - Well-known URIs
+- OAuth 2.0, OpenID Connect (for authentication)
+- TLS (RFC 8446 recommended)
+
+### Complementary Protocol
+
+**Model Context Protocol (MCP):**
+
+- Relationship clarified: MCP handles tool/resource integration, A2A handles agent-to-agent coordination
+- Protocols are complementary, not competing
+- Agents may support both protocols for different use cases
+
+---
+
+## Impact on Developers
+
+### Breaking Changes Requiring Code Updates
+
+**1. Part Type Unification (CRITICAL IMPACT)**
+
+The most significant breaking change: TextPart, FilePart, and DataPart types have been removed and replaced with a single unified Part structure.
+
+**Before (v0.3.0):**
+
+```typescript
+// Separate types with kind discriminator
+if (part.kind === "text") {
+  return part.text;
+} else if (part.kind === "file") {
+  if (part.file.fileWithUri) {
+    return fetchFile(part.file.fileWithUri);
+  } else {
+    return part.file.fileWithBytes;
+  }
+} else if (part.kind === "data") {
+  return part.data;
+}
+```
+
+**After (v1.0):**
+
+```typescript
+// Unified Part with oneof content
+if ("text" in part) {
+  return part.text;
+} else if ("url" in part) {
+  return fetchFile(part.url);
+} else if ("raw" in part) {
+  return decodeBase64(part.raw);
+} else if ("data" in part) {
+  return part.data;
+}
+```
+
+**2. Stream Event Discriminator Pattern (HIGH IMPACT)**
+
+Stream events changed from kind-based to wrapper-based discrimination:
+
+**Before (v0.3.0):**
+
+```typescript
+if (event.kind === "taskStatusUpdate") {
+  handleStatusUpdate(event);
+} else if (event.kind === "taskArtifactUpdate") {
+  handleArtifactUpdate(event);
+}
+```
+
+**After (v1.0):**
+
+```typescript
+if ("statusUpdate" in event) {
+  handleStatusUpdate(event.statusUpdate);
+} else if ("artifactUpdate" in event) {
+  handleArtifactUpdate(event.artifactUpdate);
+}
+```
+
+**3. Agent Card Structure (HIGH IMPACT)**
+
+Agent discovery and capability checking requires updates:
+
+**Before (v0.3.0):**
+
+```typescript
+const endpoint = agentCard.url;
+const transport = agentCard.preferredTransport;
+const supportsExtended = agentCard.supportsAuthenticatedExtendedCard;
+```
+
+**After (v1.0):**
+
+```typescript
+const primaryInterface = agentCard.supportedInterfaces[0];
+const endpoint = primaryInterface.url;
+const transport = primaryInterface.protocolBinding;
+const supportsExtended = agentCard.capabilities.extendedAgentCard;
+```
+
+**3. Pagination (MEDIUM IMPACT)**
+
+List Tasks implementation must switch from page-based to cursor-based:
+
+**Before (v0.3.0):**
+
+```typescript
+const response = await listTasks({ page: 1, perPage: 50 });
+```
+
+**After (v1.0):**
+
+```typescript
+let cursor = undefined;
+do {
+  const response = await listTasks({ cursor, limit: 50 });
+  // process response.tasks
+  cursor = response.nextCursor;
+} while (cursor);
+```
+
+**4. Enum Value Changes (HIGH IMPACT)**
+
+All enum values now use SCREAMING_SNAKE_CASE with type prefixes:
+
+**TaskState:**
+
+```typescript
+// v0.3.0
+if (task.status.state === "completed") { ... }
+if (task.status.state === "input-required") { ... }
+
+// v1.0
+if (task.status.state === "TASK_STATE_COMPLETED") { ... }
+if (task.status.state === "TASK_STATE_INPUT_REQUIRED") { ... }
+```
+
+**MessageRole:**
+
+```typescript
+// v0.3.0
+const message = { role: "user", parts: [...] };
+
+// v1.0  
+const message = { role: "ROLE_USER", parts: [...] };
+```
+
+**Complete Mapping:**
+- `"submitted"` → `"TASK_STATE_SUBMITTED"`
+- `"working"` → `"TASK_STATE_WORKING"`
+- `"completed"` → `"TASK_STATE_COMPLETED"`
+- `"failed"` → `"TASK_STATE_FAILED"`
+- `"cancelled"` → `"TASK_STATE_CANCELED"` (note spelling change)
+- `"rejected"` → `"TASK_STATE_REJECTED"`
+- `"input-required"` → `"TASK_STATE_INPUT_REQUIRED"`
+- `"auth-required"` → `"TASK_STATE_AUTH_REQUIRED"`
+- `"user"` → `"ROLE_USER"`
+- `"agent"` → `"ROLE_AGENT"`
+
+**5. Operation Names (LOW IMPACT)**
+
+TaskStatus state values changed:
+
+- `input-required` → `input_required`
+- `auth-required` → `auth_required`
+- `submitted` → `pending` (semantic clarification)
+
+**5. Field Name Changes (LOW IMPACT)**
+
+- `file.mimeType` → `file.mediaType`
+- Operation names (aliases provided during transition)
+
+### New Capabilities to Leverage
+
+**1. Blocking Parameter Control**
+
+```typescript
+// Wait for task completion
+const result = await sendMessage(message, { blocking: true });
+
+// Return immediately, poll later
+const task = await sendMessage(message, { blocking: false });
+```
+
+**2. Agent Card Signature Verification**
+
+```typescript
+if (agentCard.signatures && agentCard.signatures.length > 0) {
+  const verified = await verifyAgentCardSignature(agentCard);
+  if (!verified) {
+    throw new Error("Agent Card signature verification failed");
+  }
+}
+```
+
+**3. Extension Requirements**
+
+```typescript
+const requiredExtensions = agentCard.extensions
+  .filter(ext => ext.required)
+  .map(ext => ext.uri);
+
+// Check if client supports required extensions
+if (!clientSupportsAll(requiredExtensions)) {
+  throw new Error("Missing required extension support");
+}
+```
+
+**4. Enhanced Timestamp Tracking**
+
+```typescript
+const taskAge = Date.now() - new Date(task.createdAt).getTime();
+const timeSinceUpdate = Date.now() - new Date(task.lastModified).getTime();
+```
+
+**5. Versioning Negotiation**
+
+```typescript
+// Client sends A2A-Version header
+headers["A2A-Version"] = "1.0";
+
+// Server validates and rejects if unsupported
+if (!supportedVersions.includes(requestedVersion)) {
+  throw new VersionNotSupportedError();
+}
+```
+
+### Migration Strategy Recommendations
+
+**Phase 1: Compatibility Layer (Immediate)**
+
+1. Add support for parsing both old and new discriminator patterns
+2. Implement version detection based on protocol version
+3. Support both Agent Card structures during transition
+
+**Phase 2: Dual Support (1-3 months)**
+
+1. Update all APIs to emit v1.0 format
+2. Maintain backward compatibility readers for v0.3.0
+3. Add A2A-Version header handling
+4. Implement cursor-based pagination alongside legacy page-based
+
+**Phase 3: v1.0 Only (3-6 months)**
+
+1. Deprecate v0.3.0 compatibility code
+2. Remove legacy discriminator parsing
+3. Remove page-based pagination
+4. Clean up dual-format support code
+
+**Testing Considerations:**
+
+- Test with both v0.3.0 and v1.0 formatted data
+- Validate Agent Card signature verification
+- Test cursor-based pagination edge cases (empty results, single page, etc.)
+- Verify proper handling of new error types
+- Test extension requirement validation
+
+### Recommended Priority
+
+**Critical (Do Immediately):**
+
+- Update Part and streaming event parsing (discriminator pattern)
+- Update Agent Card parsing (structure changes)
+- Add A2A-Version header to all requests
+
+**High (Within 1 Month):**
+
+- Implement cursor-based pagination
+- Update enum value handling (state field)
+- Add blocking parameter support
+
+**Medium (Within 3 Months):**
+
+- Implement Agent Card signature verification
+- Add extension requirement checking
+- Update timestamp handling to ISO 8601 format
+- Implement new error types
+
+**Low (Nice to Have):**
+
+- Add createdAt/lastModified timestamp tracking
+- Leverage enhanced metadata capabilities
+- Implement mutual TLS authentication support
+
+---
+
+## Conclusion
+
+A2A Protocol v1.0 represents a significant step forward in protocol maturity while maintaining the core architectural principles of v0.3.0. The changes focus on standardization, type safety, and enterprise readiness, requiring developers to update their implementations but providing clearer specifications and better developer experience in return.
+
+The breaking changes, while requiring code updates, are straightforward to implement and improve code clarity. The new capabilities around versioning, signatures, and enhanced extensions provide a solid foundation for future protocol evolution within the v1.x line.
+
+Developers should plan for a phased migration approach, prioritizing the critical breaking changes while gradually adopting new capabilities over time.

From d42bffa4b8a7d01cc34a391be8faa4174e350031 Mon Sep 17 00:00:00 2001
From: Darrel Miller <darrel.miller@microsoft.com>
Date: Fri, 30 Jan 2026 10:37:56 -0500
Subject: [PATCH 02/12] fix(docs): Update breaking changes and specifications
 in what's new for A2A Protocol v1.0

---
 docs/whats-new-v1.md | 59 ++++++++++++++++++++++----------------------
 1 file changed, 30 insertions(+), 29 deletions(-)

diff --git a/docs/whats-new-v1.md b/docs/whats-new-v1.md
index 553ae78a5..7d45519a9 100644
--- a/docs/whats-new-v1.md
+++ b/docs/whats-new-v1.md
@@ -211,8 +211,8 @@ The v1.0 release focuses on four major themes:
 
 **Modified Fields:**
 
-- ✅ `state`: **BREAKING** - Enum values changed from lowercase/kebab-case to `SCREAMING_SNAKE_CASE` with `TASK_STATE_` prefix
-    - v0.3.0: `"submitted"`, `"working"`, `"completed"`, `"failed"`, `"cancelled"`, `"rejected"`, `"input-required"`, `"auth-required"`
+- ✅ `state`: **BREAKING** - Enum values changed from lowercase to `SCREAMING_SNAKE_CASE` with `TASK_STATE_` prefix
+    - v0.3.0: `"submitted"`, `"working"`, `"completed"`, `"failed"`, `"canceled"`, `"rejected"`, `"input-required"`, `"auth-required"`
     - v1.0: `"TASK_STATE_SUBMITTED"`, `"TASK_STATE_WORKING"`, `"TASK_STATE_COMPLETED"`, `"TASK_STATE_FAILED"`, `"TASK_STATE_CANCELED"`, `"TASK_STATE_REJECTED"`, `"TASK_STATE_INPUT_REQUIRED"`, `"TASK_STATE_AUTH_REQUIRED"`
 - ✅ `timestamp`: Now explicitly ISO 8601 UTC with millisecond precision (YYYY-MM-DDTHH:mm:ss.sssZ)
 - ✅ `message`: Optional Message with enhanced extension support
@@ -588,33 +588,33 @@ v1.0 introduces several new formal dependencies on industry-standard specificati
 
 ### Added Specifications
 
-**✅ RFC 9457 - Problem Details for HTTP APIs**
+#### ✅ RFC 9457 - Problem Details for HTTP APIs
 
 - **Purpose:** Standardized error response format
 - **Usage:** HTTP+JSON binding error responses
 - **Impact:** More consistent, machine-readable error handling in REST APIs
 
-**✅ RFC 8785 - JSON Canonicalization Scheme (JCS)**
+#### ✅ RFC 8785 - JSON Canonicalization Scheme (JCS)
 
 - **Purpose:** Deterministic JSON serialization for signing
 - **Usage:** Agent Card signature verification
 - **Impact:** Enables cryptographic verification of Agent Card integrity
 - **Details:** Canonical form used before JWS signing (excludes `signatures` field)
 
-**✅ RFC 7515 - JSON Web Signature (JWS)**
+#### ✅ RFC 7515 - JSON Web Signature (JWS)
 
 - **Purpose:** Cryptographic signing standard
 - **Usage:** Agent Card signatures field
 - **Impact:** Industry-standard signature format for trust verification
 - **Details:** Supports detached signatures with public key retrieval via `jku` or trusted keystores
 
-**✅ Google API Design Guidelines**
+#### ✅ Google API Design Guidelines
 
 - **Purpose:** gRPC best practices and conventions
 - **Usage:** gRPC binding design patterns
 - **Impact:** Better alignment with gRPC ecosystem expectations
 
-**✅ ISO 8601**
+#### ✅ ISO 8601
 
 - **Purpose:** Timestamp format standard
 - **Usage:** All timestamp fields (createdAt, lastModified, timestamp)
@@ -644,7 +644,7 @@ v1.0 introduces several new formal dependencies on industry-standard specificati
 
 ### Breaking Changes Requiring Code Updates
 
-**1. Part Type Unification (CRITICAL IMPACT)**
+#### 1. Part Type Unification (CRITICAL IMPACT)
 
 The most significant breaking change: TextPart, FilePart, and DataPart types have been removed and replaced with a single unified Part structure.
 
@@ -680,7 +680,7 @@ if ("text" in part) {
 }
 ```
 
-**2. Stream Event Discriminator Pattern (HIGH IMPACT)**
+#### 2. Stream Event Discriminator Pattern (HIGH IMPACT)
 
 Stream events changed from kind-based to wrapper-based discrimination:
 
@@ -704,7 +704,7 @@ if ("statusUpdate" in event) {
 }
 ```
 
-**3. Agent Card Structure (HIGH IMPACT)**
+#### 3. Agent Card Structure (HIGH IMPACT)
 
 Agent discovery and capability checking requires updates:
 
@@ -725,7 +725,7 @@ const transport = primaryInterface.protocolBinding;
 const supportsExtended = agentCard.capabilities.extendedAgentCard;
 ```
 
-**3. Pagination (MEDIUM IMPACT)**
+#### 4. Pagination (MEDIUM IMPACT)
 
 List Tasks implementation must switch from page-based to cursor-based:
 
@@ -746,7 +746,7 @@ do {
 } while (cursor);
 ```
 
-**4. Enum Value Changes (HIGH IMPACT)**
+#### 5. Enum Value Changes (HIGH IMPACT)
 
 All enum values now use SCREAMING_SNAKE_CASE with type prefixes:
 
@@ -768,23 +768,24 @@ if (task.status.state === "TASK_STATE_INPUT_REQUIRED") { ... }
 // v0.3.0
 const message = { role: "user", parts: [...] };
 
-// v1.0  
+// v1.0
 const message = { role: "ROLE_USER", parts: [...] };
 ```
 
 **Complete Mapping:**
+
 - `"submitted"` → `"TASK_STATE_SUBMITTED"`
 - `"working"` → `"TASK_STATE_WORKING"`
 - `"completed"` → `"TASK_STATE_COMPLETED"`
 - `"failed"` → `"TASK_STATE_FAILED"`
-- `"cancelled"` → `"TASK_STATE_CANCELED"` (note spelling change)
+- `"canceled"` → `"TASK_STATE_CANCELED"`
 - `"rejected"` → `"TASK_STATE_REJECTED"`
 - `"input-required"` → `"TASK_STATE_INPUT_REQUIRED"`
 - `"auth-required"` → `"TASK_STATE_AUTH_REQUIRED"`
 - `"user"` → `"ROLE_USER"`
 - `"agent"` → `"ROLE_AGENT"`
 
-**5. Operation Names (LOW IMPACT)**
+#### 6. Operation Names (LOW IMPACT)
 
 TaskStatus state values changed:
 
@@ -792,14 +793,14 @@ TaskStatus state values changed:
 - `auth-required` → `auth_required`
 - `submitted` → `pending` (semantic clarification)
 
-**5. Field Name Changes (LOW IMPACT)**
+#### 7. Field Name Changes (LOW IMPACT)
 
 - `file.mimeType` → `file.mediaType`
 - Operation names (aliases provided during transition)
 
 ### New Capabilities to Leverage
 
-**1. Blocking Parameter Control**
+#### 1. Blocking Parameter Control
 
 ```typescript
 // Wait for task completion
@@ -809,7 +810,7 @@ const result = await sendMessage(message, { blocking: true });
 const task = await sendMessage(message, { blocking: false });
 ```
 
-**2. Agent Card Signature Verification**
+#### 2. Agent Card Signature Verification
 
 ```typescript
 if (agentCard.signatures && agentCard.signatures.length > 0) {
@@ -820,7 +821,7 @@ if (agentCard.signatures && agentCard.signatures.length > 0) {
 }
 ```
 
-**3. Extension Requirements**
+#### 3. Extension Requirements
 
 ```typescript
 const requiredExtensions = agentCard.extensions
@@ -833,14 +834,14 @@ if (!clientSupportsAll(requiredExtensions)) {
 }
 ```
 
-**4. Enhanced Timestamp Tracking**
+#### 4. Enhanced Timestamp Tracking
 
 ```typescript
 const taskAge = Date.now() - new Date(task.createdAt).getTime();
 const timeSinceUpdate = Date.now() - new Date(task.lastModified).getTime();
 ```
 
-**5. Versioning Negotiation**
+#### 5. Versioning Negotiation
 
 ```typescript
 // Client sends A2A-Version header
@@ -854,27 +855,27 @@ if (!supportedVersions.includes(requestedVersion)) {
 
 ### Migration Strategy Recommendations
 
-**Phase 1: Compatibility Layer (Immediate)**
+#### Phase 1: Compatibility Layer (Immediate)
 
 1. Add support for parsing both old and new discriminator patterns
 2. Implement version detection based on protocol version
 3. Support both Agent Card structures during transition
 
-**Phase 2: Dual Support (1-3 months)**
+#### Phase 2: Dual Support (1-3 months)
 
 1. Update all APIs to emit v1.0 format
 2. Maintain backward compatibility readers for v0.3.0
 3. Add A2A-Version header handling
 4. Implement cursor-based pagination alongside legacy page-based
 
-**Phase 3: v1.0 Only (3-6 months)**
+#### Phase 3: v1.0 Only (3-6 months)
 
 1. Deprecate v0.3.0 compatibility code
 2. Remove legacy discriminator parsing
 3. Remove page-based pagination
 4. Clean up dual-format support code
 
-**Testing Considerations:**
+#### Testing Considerations
 
 - Test with both v0.3.0 and v1.0 formatted data
 - Validate Agent Card signature verification
@@ -884,26 +885,26 @@ if (!supportedVersions.includes(requestedVersion)) {
 
 ### Recommended Priority
 
-**Critical (Do Immediately):**
+#### Critical (Do Immediately)
 
 - Update Part and streaming event parsing (discriminator pattern)
 - Update Agent Card parsing (structure changes)
 - Add A2A-Version header to all requests
 
-**High (Within 1 Month):**
+#### High (Within 1 Month)
 
 - Implement cursor-based pagination
 - Update enum value handling (state field)
 - Add blocking parameter support
 
-**Medium (Within 3 Months):**
+#### Medium (Within 3 Months)
 
 - Implement Agent Card signature verification
 - Add extension requirement checking
 - Update timestamp handling to ISO 8601 format
 - Implement new error types
 
-**Low (Nice to Have):**
+#### Low (Nice to Have)
 
 - Add createdAt/lastModified timestamp tracking
 - Leverage enhanced metadata capabilities

From 7f5eef2a65d5e6edca1cb126b81dd3833070c71b Mon Sep 17 00:00:00 2001
From: Darrel Miller <darrel.miller@microsoft.com>
Date: Fri, 30 Jan 2026 11:11:36 -0500
Subject: [PATCH 03/12] feat(docs): Enhance 'What's New' documentation with
 multi-tenancy support and OAuth 2.0 updates

---
 docs/whats-new-v1.md | 168 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 167 insertions(+), 1 deletion(-)

diff --git a/docs/whats-new-v1.md b/docs/whats-new-v1.md
index 7d45519a9..534450c4b 100644
--- a/docs/whats-new-v1.md
+++ b/docs/whats-new-v1.md
@@ -27,12 +27,17 @@ The v1.0 release focuses on four major themes:
 - Reorganized Agent Card structure for better logical grouping
 - Enhanced extension mechanism with versioning and requirement declarations
 - More explicit service parameter handling (A2A-Version, A2A-Extensions headers)
+- **Simplified ID format** - Removed complex compound IDs (e.g., `tasks/{id}`) in favor of simple UUIDs
+- **Protocol versioning per interface** - Each AgentInterface specifies its own protocol version for better backward compatibility
+- **Multi-tenancy support** - Native tenant scoping in gRPC requests
 
 ### 4. **Enterprise-Ready Features**
 
 - Agent Card signature verification using JWS and JSON Canonicalization
 - Formal specification of all three protocol bindings with equivalence guarantees
 - Enhanced security scheme declarations with mutual TLS support
+- **Modern OAuth 2.0 flows** - Added Device Code flow (RFC 8628), removed deprecated implicit/password flows
+- **PKCE support** - Added `pkce_required` field to Authorization Code flow for enhanced security
 - Cursor-based pagination for scalable task listing
 
 ---
@@ -179,6 +184,60 @@ The v1.0 release focuses on four major themes:
 - **✅ CLARIFIED:** Push notification payloads now use StreamResponse format
 - **✅ NEW:** Explicit `PushNotificationNotSupportedError` when capability not available
 
+### NEW: Multi-Tenancy Support
+
+**v0.3.0:**
+
+- No native multi-tenancy support in protocol
+- Tenants handled implicitly via authentication or URL paths
+
+**v1.0 Changes:**
+
+- **✅ NEW:** `tenant` field added to all gRPC request messages
+- **✅ NEW:** `tenant` field added to `AgentInterface` to specify default tenant
+- **✅ CLARIFIED:** Tenant can be provided per-request or inherited from AgentInterface
+- **✅ USE CASE:** Enables agents to serve multiple organizations from single endpoint
+
+**Example:**
+
+```protobuf
+message SendMessageRequest {
+  string tenant = 1;  // Optional tenant identifier
+  Message message = 2;
+  SendMessageConfiguration configuration = 3;
+}
+```
+
+### Protocol Simplifications
+
+#### ID Format Simplification (#1389)
+
+**v0.3.0:**
+
+- Some operations used complex compound IDs like `tasks/{taskId}`
+- Required clients/servers to construct/deconstruct resource names
+
+**v1.0 Changes:**
+
+- **✅ BREAKING:** All IDs are now simple literals
+- **✅ BREAKING:** Operations that previously used compound IDs now separate parent and resource ID
+    - Example: `tasks/{taskId}/pushNotificationConfigs/{configId}` → separate `task_id` and `config_id` fields
+- **✅ BENEFIT:** Simpler to implement - IDs map directly to database keys
+
+#### HTTP URL Path Simplification (#1269)
+
+**v0.3.0:**
+
+- HTTP+JSON binding used `/v1/` prefix in URLs
+- Example: `POST /v1/message:send`
+
+**v1.0 Changes:**
+
+- **✅ BREAKING:** Removed `/v1` prefix from HTTP+JSON URL paths
+- **✅ NEW:** Examples: `POST /message:send`, `GET /tasks/{id}`
+- **✅ RATIONALE:** Version specified in `AgentInterface.protocolVersion` field instead
+- **✅ BENEFIT:** Cleaner URLs, version management at interface level
+
 ---
 
 ## Structural Changes in Core Model Objects
@@ -481,6 +540,28 @@ if ("text" in part) { ... }         // v1.0
 - ✅ **SIMPLIFIED:** Description remains, but structure dramatically simplified
 - ✅ **PATTERN:** Extension versioning now embedded in URI (e.g., `/v1`, `/v2`)
 
+### AgentCapabilities Object
+
+**Removed Fields:**
+
+- ⛔ `stateTransitionHistory` (#1396) - Removed as no API implementation existed for this feature
+
+**Rationale:**
+
+The `stateTransitionHistory` capability flag was misleading as v1.0 has no corresponding API to:
+
+- Store status history in Task objects
+- Retrieve status history via Get/List operations
+- Query historical state transitions
+
+This capability may be reintroduced in a future version with proper implementation.
+
+**Modified Fields:**
+
+- ✅ `extendedAgentCard`: Moved from top-level `supportsAuthenticatedExtendedCard` field
+- ✅ `pushNotifications`: More formally specified with enhanced configuration options
+- ✅ `streaming`: Enhanced with clearer semantics for SSE support
+
 ### SecurityScheme Objects
 
 **Added:**
@@ -580,6 +661,51 @@ if ("text" in part) { ... }         // v1.0
 - ✅ **NEW PATTERN:** Wrapped in `taskArtifactUpdate` object
 - ✅ **NEW:** `index` field indicates artifact position in task's artifacts array
 
+### OAuth 2.0 Security Updates (#1303)
+
+v1.0 modernizes OAuth 2.0 support in alignment with OAuth 2.0 Security Best Current Practice (BCP).
+
+**Removed Flows (Deprecated by OAuth BCP):**
+
+- ⛔ `ImplicitOAuthFlow` - Deprecated due to token leakage risks in browser history/logs
+- ⛔ `PasswordOAuthFlow` - Deprecated due to credential exposure risks
+
+**Added Flows:**
+
+- ✅ `DeviceCodeOAuthFlow` (RFC 8628) - For CLI tools, IoT devices, and input-constrained scenarios
+    - Provides `device_authorization_url` endpoint
+    - Supports `verification_uri`, `user_code` pattern
+    - Ideal for headless environments
+
+**Enhanced Security:**
+
+- ✅ `pkce_required` field added to `AuthorizationCodeOAuthFlow` (RFC 7636)
+    - Indicates whether PKCE (Proof Key for Code Exchange) is mandatory
+    - Protects against authorization code interception attacks
+    - Recommended for all OAuth clients, required for public clients
+
+**Migration Guide:**
+
+```typescript
+// v0.3.0 - Implicit Flow (now removed)
+{
+  "implicitFlow": {
+    "authorizationUrl": "https://auth.example.com/authorize",
+    "scopes": {"read": "Read access"}
+  }
+}
+
+// v1.0 - Use Authorization Code + PKCE instead
+{
+  "authorizationCodeFlow": {
+    "authorizationUrl": "https://auth.example.com/authorize",
+    "tokenUrl": "https://auth.example.com/token",
+    "pkceRequired": true,
+    "scopes": {"read": "Read access"}
+  }
+}
+```
+
 ---
 
 ## New Dependencies on Other Specifications
@@ -875,7 +1001,47 @@ if (!supportedVersions.includes(requestedVersion)) {
 3. Remove page-based pagination
 4. Clean up dual-format support code
 
-#### Testing Considerations
+#### Backward Compatibility Strategy (#1401)
+
+v1.0 introduces a formal approach to protocol versioning that enables SDK backward compatibility.
+
+**Protocol Version Per Interface:**
+
+- Each `AgentInterface` now specifies its own `protocolVersion` field
+- Agents can support multiple protocol versions simultaneously by exposing multiple interfaces
+- Clients negotiate version by selecting appropriate interface from Agent Card
+
+**SDK Implementation Pattern:**
+
+```typescript
+// SDK can support multiple protocol versions
+class A2AClient {
+  async connect(agentCardUrl: string) {
+    const card = await this.getAgentCard(agentCardUrl);
+
+    // Find best matching interface
+    const interface = card.supportedInterfaces.find(i =>
+      this.supportedVersions.includes(i.protocolVersion)
+    );
+
+    if (!interface) {
+      throw new Error('No compatible protocol version');
+    }
+
+    // Use version-specific adapter
+    return this.createAdapter(interface.protocolVersion, interface);
+  }
+}
+```
+
+**Benefits:**
+
+- SDKs can maintain support for multiple protocol versions
+- Agents can gradually migrate by supporting both old and new versions
+- Clients automatically select best compatible version
+- Enables graceful deprecation of old protocol versions
+
+### Testing Considerations
 
 - Test with both v0.3.0 and v1.0 formatted data
 - Validate Agent Card signature verification

From 8c6455c9d1f952f323cabc2a98a673245077eab5 Mon Sep 17 00:00:00 2001
From: Darrel Miller <darrel.miller@microsoft.com>
Date: Fri, 30 Jan 2026 11:15:34 -0500
Subject: [PATCH 04/12] fix(docs): Update wording for clarity in 'What's New'
 documentation

---
 docs/whats-new-v1.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/whats-new-v1.md b/docs/whats-new-v1.md
index 534450c4b..124626a14 100644
--- a/docs/whats-new-v1.md
+++ b/docs/whats-new-v1.md
@@ -8,7 +8,7 @@ The v1.0 release focuses on four major themes:
 
 ### 1. **Protocol Maturity and Standardization**
 
-- Migration to formal specification standards (RFC 9457, RFC 8785, RFC 7515)
+- Leverage formal specification standards (RFC 9457, RFC 8785, RFC 7515) where possible
 - Stricter adherence to industry-standard patterns for REST, gRPC, and JSON-RPC bindings
 - Enhanced versioning strategy with explicit backward compatibility rules
 - Comprehensive error taxonomy with protocol-specific mappings

From e89b10a87d48f03833dd8f59a1cb0a3a81e3506a Mon Sep 17 00:00:00 2001
From: Darrel Miller <darrel.miller@microsoft.com>
Date: Fri, 30 Jan 2026 13:33:48 -0500
Subject: [PATCH 05/12] Fixed gemini review comments

---
 docs/whats-new-v1.md | 20 ++++++--------------
 1 file changed, 6 insertions(+), 14 deletions(-)

diff --git a/docs/whats-new-v1.md b/docs/whats-new-v1.md
index 124626a14..0100536d1 100644
--- a/docs/whats-new-v1.md
+++ b/docs/whats-new-v1.md
@@ -823,10 +823,10 @@ if (event.kind === "taskStatusUpdate") {
 **After (v1.0):**
 
 ```typescript
-if ("statusUpdate" in event) {
-  handleStatusUpdate(event.statusUpdate);
-} else if ("artifactUpdate" in event) {
-  handleArtifactUpdate(event.artifactUpdate);
+if ("taskStatusUpdate" in event) {
+  handleStatusUpdate(event.taskStatusUpdate);
+} else if ("taskArtifactUpdate" in event) {
+  handleArtifactUpdate(event.taskArtifactUpdate);
 }
 ```
 
@@ -911,17 +911,9 @@ const message = { role: "ROLE_USER", parts: [...] };
 - `"user"` → `"ROLE_USER"`
 - `"agent"` → `"ROLE_AGENT"`
 
-#### 6. Operation Names (LOW IMPACT)
+#### 6. Field Name Changes (LOW IMPACT)
 
-TaskStatus state values changed:
-
-- `input-required` → `input_required`
-- `auth-required` → `auth_required`
-- `submitted` → `pending` (semantic clarification)
-
-#### 7. Field Name Changes (LOW IMPACT)
-
-- `file.mimeType` → `file.mediaType`
+- `file.mimeType` → `mediaType`
 - Operation names (aliases provided during transition)
 
 ### New Capabilities to Leverage

From 7f0fd964bd1352455558c363273a8fda719bee27 Mon Sep 17 00:00:00 2001
From: Darrel <darrmi@microsoft.com>
Date: Fri, 30 Jan 2026 13:34:44 -0500
Subject: [PATCH 06/12] Update docs/whats-new-v1.md

Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
---
 docs/whats-new-v1.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/whats-new-v1.md b/docs/whats-new-v1.md
index 0100536d1..c8753eb04 100644
--- a/docs/whats-new-v1.md
+++ b/docs/whats-new-v1.md
@@ -54,7 +54,7 @@ The v1.0 release focuses on four major themes:
 
 **v1.0 Changes:**
 
-- **✅ NEW:** Operation formally named **SendMessage** (with legacy alias support)
+- **✅ NEW:** Operation formally named **`SendMessage`** (with legacy alias support)
 - **✅ NEW:** `SendMessageConfiguration.blocking` parameter explicitly controls wait behavior
     - `blocking: true` - Server waits until task reaches terminal or interrupted state
     - `blocking: false` - Server returns immediately; client polls/streams for updates

From 959dc084c6069d6132bd16847ab080dfb6be5810 Mon Sep 17 00:00:00 2001
From: Darrel <darrmi@microsoft.com>
Date: Fri, 30 Jan 2026 13:35:44 -0500
Subject: [PATCH 07/12] Update docs/whats-new-v1.md

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
---
 docs/whats-new-v1.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/whats-new-v1.md b/docs/whats-new-v1.md
index c8753eb04..d86c6054b 100644
--- a/docs/whats-new-v1.md
+++ b/docs/whats-new-v1.md
@@ -164,7 +164,7 @@ The v1.0 release focuses on four major themes:
 - **✅ CLARIFIED:** Formal specification of streaming subscription lifecycle
 - **✅ CLARIFIED:** Stream closure behavior when task reaches terminal state
 - **✅ CLARIFIED:** Multiple concurrent subscriptions supported per task
-- **✅ BEHAVIOURCHANGE:** Can subscribe to tasks not originally created via streaming
+- **✅ BEHAVIOR CHANGE:** Can subscribe to tasks not originally created via streaming
 
 ### Push Notification Operations
 

From 640b240a8537eaadecf83b598d0dfc2ef7b92154 Mon Sep 17 00:00:00 2001
From: Darrel <darrmi@microsoft.com>
Date: Fri, 30 Jan 2026 13:37:24 -0500
Subject: [PATCH 08/12] Apply suggestions from code review

Co-authored-by: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
---
 docs/whats-new-v1.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/whats-new-v1.md b/docs/whats-new-v1.md
index d86c6054b..5908131eb 100644
--- a/docs/whats-new-v1.md
+++ b/docs/whats-new-v1.md
@@ -17,7 +17,7 @@ The v1.0 release focuses on four major themes:
 
 - Removal of discriminator `kind` fields in favor of JSON member-based polymorphism
 - **Breaking:** Enum values changed from `PascalCase` to `SCREAMING_SNAKE_CASE` for consistency
-- Stricter field naming conventions (camelCase for JSON)
+- Stricter field naming conventions (`camelCase` for JSON)
 - More precise timestamp specifications (ISO 8601 with millisecond precision)
 - Better-defined data types with clearer Optional vs Required semantics
 
@@ -44,13 +44,13 @@ The v1.0 release focuses on four major themes:
 
 ## Behavioral Changes for Core Operations
 
-### Send Message (`message/send` → **SendMessage**)
+### Send Message (`message/send` → **`SendMessage`**)
 
 **v0.3.0 Behavior:**
 
 - Operation named `message/send`
 - Blocking behavior not explicitly controllable
-- Less formal specification of when Task vs Message is returned
+- Less formal specification of when `Task` vs `Message` is returned
 
 **v1.0 Changes:**
 
@@ -75,9 +75,9 @@ The v1.0 release focuses on four major themes:
 
 **v1.0 Changes:**
 
-- **✅ RENAMED:** Operation now **SendStreamingMessage**
+- **✅ RENAMED:** Operation now **`SendStreamingMessage`**
 - **✅ BREAKING:** Stream events no longer have `kind` field
-    - Use JSON member names to discriminate between TaskStatusUpdateEvent and TaskArtifactUpdateEvent
+    - Use JSON member names to discriminate between `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent`
 - **✅ NEW:** Formal gRPC streaming semantics defined
 - **✅ REMOVED:** `final` boolean field removed from TaskStatusUpdateEvent. Leverage protocol binding specific stream closure mechanism instead.
 - **✅ CLARIFIED:** Multiple concurrent streams allowed; all receive same ordered events

From fc607e256d992a917681b42244d62ae31c2c8038 Mon Sep 17 00:00:00 2001
From: Darrel Miller <darrel.miller@microsoft.com>
Date: Fri, 30 Jan 2026 13:39:39 -0500
Subject: [PATCH 09/12] Removed time esitmates from migration strategy

---
 docs/whats-new-v1.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/whats-new-v1.md b/docs/whats-new-v1.md
index 5908131eb..9e264f9c4 100644
--- a/docs/whats-new-v1.md
+++ b/docs/whats-new-v1.md
@@ -973,20 +973,20 @@ if (!supportedVersions.includes(requestedVersion)) {
 
 ### Migration Strategy Recommendations
 
-#### Phase 1: Compatibility Layer (Immediate)
+#### Phase 1: Compatibility Layer
 
 1. Add support for parsing both old and new discriminator patterns
 2. Implement version detection based on protocol version
 3. Support both Agent Card structures during transition
 
-#### Phase 2: Dual Support (1-3 months)
+#### Phase 2: Dual Support
 
 1. Update all APIs to emit v1.0 format
 2. Maintain backward compatibility readers for v0.3.0
 3. Add A2A-Version header handling
 4. Implement cursor-based pagination alongside legacy page-based
 
-#### Phase 3: v1.0 Only (3-6 months)
+#### Phase 3: v1.0 Only
 
 1. Deprecate v0.3.0 compatibility code
 2. Remove legacy discriminator parsing

From 0135ef4b7a8b2f9f6fbdd6bbb5eaf8a005b039f1 Mon Sep 17 00:00:00 2001
From: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Date: Tue, 3 Feb 2026 10:49:56 -0600
Subject: [PATCH 10/12] Update docs/whats-new-v1.md

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
---
 docs/whats-new-v1.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/whats-new-v1.md b/docs/whats-new-v1.md
index 9e264f9c4..ebadfc554 100644
--- a/docs/whats-new-v1.md
+++ b/docs/whats-new-v1.md
@@ -428,7 +428,7 @@ const dataPart = { data: { key: "value" }, mediaType: "application/json" };
 
 // Discrimination changed from kind field to member presence
 if (part.kind === "text") { ... }  // v0.3.0
-if ("text" in part) { ... }         // v1.0
+if ("text" in part) { ... }        // v1.0
 ```
 
 ### Artifact Object

From d4760a0913dcf41902c8cd50f3e8790e92ea9ad4 Mon Sep 17 00:00:00 2001
From: Holt Skinner <13262395+holtskinner@users.noreply.github.com>
Date: Thu, 5 Feb 2026 10:39:25 -0600
Subject: [PATCH 11/12] Update docs/whats-new-v1.md

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
---
 docs/whats-new-v1.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/whats-new-v1.md b/docs/whats-new-v1.md
index ebadfc554..45988322f 100644
--- a/docs/whats-new-v1.md
+++ b/docs/whats-new-v1.md
@@ -1017,7 +1017,7 @@ class A2AClient {
     );
 
     if (!interface) {
-      throw new Error('No compatible protocol version');
+      throw new Error("No compatible protocol version");
     }
 
     // Use version-specific adapter

From dc447983229484e8929c3aaafaf157d4fe5aadd8 Mon Sep 17 00:00:00 2001
From: Darrel <darrmi@microsoft.com>
Date: Thu, 5 Feb 2026 12:01:42 -0500
Subject: [PATCH 12/12] Update docs/whats-new-v1.md

---
 docs/whats-new-v1.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/whats-new-v1.md b/docs/whats-new-v1.md
index 45988322f..b305fb5bd 100644
--- a/docs/whats-new-v1.md
+++ b/docs/whats-new-v1.md
@@ -16,7 +16,7 @@ The v1.0 release focuses on four major themes:
 ### 2. **Enhanced Type Safety and Clarity**
 
 - Removal of discriminator `kind` fields in favor of JSON member-based polymorphism
-- **Breaking:** Enum values changed from `PascalCase` to `SCREAMING_SNAKE_CASE` for consistency
+- **Breaking:** Enum values changed from `kebab-case` to `SCREAMING_SNAKE_CASE` for compliance with the ProtoJSON specification
 - Stricter field naming conventions (`camelCase` for JSON)
 - More precise timestamp specifications (ISO 8601 with millisecond precision)
 - Better-defined data types with clearer Optional vs Required semantics