@bluefly/openstandardagents 0.3.2 → 0.3.5

package/spec/v0.2.9/a2a-protocol.md

@@ -1,1337 +0,0 @@
-# OSSA Agent-to-Agent (A2A) Protocol Specification
-
-**Version**: 0.2.9
-**Status**: Draft
-**Last Updated**: 2025-12-04
-
-This document defines the Agent-to-Agent (A2A) Protocol for multi-agent communication in OSSA-compliant systems. The A2A protocol enables agents to discover, authenticate, and communicate with each other using standardized message formats and routing patterns.
-
-## 1. Overview
-
-The A2A Protocol provides:
-- **Discovery**: Agents advertise capabilities via AgentCard
-- **Authentication**: mTLS, JWT bearer tokens, and OIDC
-- **Routing**: Direct, broadcast, topic-based, and request/response patterns
-- **Task Lifecycle**: Standard states for collaborative work
-- **Streaming**: Support for long-running tasks with progress updates
-- **Push Notifications**: Real-time event delivery
-
-### Design Principles
-
-1. **Interoperability**: Works across different OSSA runtime implementations
-2. **Security**: Authentication and encryption by default
-3. **Scalability**: Supports peer-to-peer and hub-spoke topologies
-4. **Observability**: Full W3C trace context propagation
-5. **Simplicity**: Minimal protocol overhead
-
----
-
-## 2. Message Envelope Format
-
-All A2A messages MUST use the following envelope structure:
-
-```yaml
-# Message Envelope (v0.2.9)
-version: "ossa/a2a/v0.2.9"
-id: "msg_2kj3h4k2j3h4k"                    # Unique message ID (UUID v7 recommended)
-timestamp: "2025-12-04T19:30:00.000Z"      # ISO 8601 timestamp
-from: "agent://team-a/code-reviewer"       # Sender agent URI
-to: "agent://team-b/code-analyzer"         # Recipient agent URI (or topic)
-correlation_id: "req_abc123"               # Groups related messages
-reply_to: "agent://team-a/code-reviewer"   # Optional: where to send response
-ttl: 300                                   # Time-to-live in seconds
-priority: "normal"                         # normal | high | urgent
-type: "request"                            # request | response | event | command
-payload:
-  # Application-specific payload (see sections below)
-  action: "analyze_code"
-  data:
-    repository: "https://github.com/org/repo"
-    commit_sha: "abc123"
-```
-
-### Envelope Fields
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `version` | string | Yes | Protocol version (MUST be `ossa/a2a/v0.2.9`) |
-| `id` | string | Yes | Unique message identifier (UUID) |
-| `timestamp` | ISO8601 | Yes | Message creation time |
-| `from` | URI | Yes | Sender agent URI |
-| `to` | URI | Yes | Recipient agent URI or topic |
-| `correlation_id` | string | No | Groups request/response pairs |
-| `reply_to` | URI | No | Where to send responses |
-| `ttl` | integer | No | Time-to-live in seconds (default: 300) |
-| `priority` | enum | No | Message priority (default: normal) |
-| `type` | enum | Yes | Message type (request/response/event/command) |
-| `payload` | object | Yes | Application-specific message content |
-
-### Message Types
-
-```typescript
-type MessageType =
-  | 'request'    // Expects a response
-  | 'response'   // Reply to a request
-  | 'event'      // Fire-and-forget notification
-  | 'command';   // Imperative action (no response expected)
-```
-
----
-
-## 3. Discovery Mechanism
-
-Agents discover each other through three methods:
-
-### 3.1 Registry-Based Discovery
-
-Agents register with a central registry (e.g., Consul, etcd, OSSA Registry).
-
-```yaml
-# Register agent
-POST /registry/agents
-Content-Type: application/json
-
-{
-  "agent_card": {
-    "uri": "agent://team-a/code-reviewer",
-    "name": "Code Review Agent",
-    "version": "1.2.3",
-    "capabilities": [
-      "code_analysis",
-      "security_scanning",
-      "style_checking"
-    ],
-    "endpoints": {
-      "http": "https://agents.example.com/code-reviewer",
-      "grpc": "grpc://agents.example.com:50051/code-reviewer"
-    },
-    "transport": ["http", "grpc"],
-    "authentication": ["mtls", "bearer"],
-    "ossa_version": "0.2.9",
-    "metadata": {
-      "team": "engineering",
-      "environment": "production",
-      "region": "us-west-2"
-    }
-  },
-  "ttl": 60  # Re-register every 60 seconds (heartbeat)
-}
-```
-
-Query registry:
-
-```yaml
-# Find agents by capability
-GET /registry/agents?capability=code_analysis
-
-# Response
-{
-  "agents": [
-    {
-      "uri": "agent://team-a/code-reviewer",
-      "capabilities": ["code_analysis", "security_scanning"],
-      "endpoints": {
-        "http": "https://agents.example.com/code-reviewer"
-      },
-      "last_heartbeat": "2025-12-04T19:30:00.000Z",
-      "status": "healthy"
-    }
-  ]
-}
-```
-
-### 3.2 Broadcast Discovery (DNS-SD)
-
-Agents broadcast presence via DNS Service Discovery (RFC 6763).
-
-```bash
-# Publish agent via Avahi/Bonjour
-dns-sd -R "Code Reviewer" _ossa-agent._tcp local 8080 \
-  uri=agent://team-a/code-reviewer \
-  version=0.2.9 \
-  capabilities=code_analysis,security_scanning
-
-# Discover agents
-dns-sd -B _ossa-agent._tcp local
-```
-
-**AgentCard via DNS TXT Record**:
-
-```
-_ossa-agent._tcp.local.
-  PTR code-reviewer.ossa-agent._tcp.local.
-
-code-reviewer._ossa-agent._tcp.local.
-  SRV 0 0 8080 agent-host.local.
-  TXT "uri=agent://team-a/code-reviewer"
-  TXT "version=0.2.9"
-  TXT "capabilities=code_analysis,security_scanning"
-  TXT "transport=http,grpc"
-  TXT "auth=mtls"
-```
-
-### 3.3 Multicast Discovery (mDNS)
-
-Agents use multicast DNS for local network discovery.
-
-```yaml
-# mDNS announcement packet
-type: PTR
-name: _ossa-agent._tcp.local
-data: code-reviewer._ossa-agent._tcp.local
-
-type: SRV
-name: code-reviewer._ossa-agent._tcp.local
-priority: 0
-weight: 0
-port: 8080
-target: agent-host.local
-
-type: TXT
-name: code-reviewer._ossa-agent._tcp.local
-data:
-  - "uri=agent://team-a/code-reviewer"
-  - "capabilities=code_analysis"
-  - "ossa_version=0.2.9"
-```
-
----
-
-## 4. AgentCard Schema
-
-The AgentCard is a self-describing document that advertises agent capabilities.
-
-```typescript
-interface AgentCard {
-  // Identity
-  uri: string;                    // Unique agent URI
-  name: string;                   // Human-readable name
-  version: string;                // Semantic version
-  ossa_version: string;           // OSSA spec version
-
-  // Capabilities
-  capabilities: string[];         // Advertised capabilities
-  tools?: ToolDescriptor[];       // Available tools
-  role?: string;                  // Agent role/specialty
-
-  // Connectivity
-  endpoints: {
-    http?: string;                // HTTP/REST endpoint
-    grpc?: string;                // gRPC endpoint
-    websocket?: string;           // WebSocket endpoint
-  };
-  transport: Transport[];         // Supported transports
-
-  // Security
-  authentication: AuthMethod[];   // Supported auth methods
-  encryption: EncryptionSpec;     // Encryption requirements
-
-  // Metadata
-  metadata?: {
-    team?: string;
-    environment?: string;
-    region?: string;
-    [key: string]: unknown;
-  };
-
-  // Health
-  status?: 'healthy' | 'degraded' | 'unavailable';
-  last_heartbeat?: string;        // ISO 8601 timestamp
-}
-
-type Transport = 'http' | 'grpc' | 'websocket' | 'mqtt';
-type AuthMethod = 'mtls' | 'bearer' | 'oidc' | 'api_key';
-
-interface ToolDescriptor {
-  name: string;
-  description: string;
-  input_schema: JSONSchema;
-  output_schema?: JSONSchema;
-}
-
-interface EncryptionSpec {
-  tls_required: boolean;
-  min_tls_version: '1.2' | '1.3';
-  cipher_suites?: string[];
-}
-```
-
-### AgentCard Example
-
-```yaml
-uri: "agent://team-a/code-reviewer"
-name: "Code Review Agent"
-version: "1.2.3"
-ossa_version: "0.2.9"
-
-capabilities:
-  - code_analysis
-  - security_scanning
-  - style_checking
-
-tools:
-  - name: analyze_code
-    description: "Perform static code analysis"
-    input_schema:
-      type: object
-      required: [repository, commit_sha]
-      properties:
-        repository:
-          type: string
-          format: uri
-        commit_sha:
-          type: string
-          pattern: "^[0-9a-f]{40}$"
-
-  - name: check_security
-    description: "Scan code for security vulnerabilities"
-    input_schema:
-      type: object
-      required: [code]
-      properties:
-        code:
-          type: string
-
-endpoints:
-  http: "https://agents.example.com/code-reviewer"
-  grpc: "grpc://agents.example.com:50051/code-reviewer"
-
-transport:
-  - http
-  - grpc
-
-authentication:
-  - mtls
-  - bearer
-
-encryption:
-  tls_required: true
-  min_tls_version: "1.3"
-  cipher_suites:
-    - "TLS_AES_256_GCM_SHA384"
-    - "TLS_CHACHA20_POLY1305_SHA256"
-
-metadata:
-  team: "engineering"
-  environment: "production"
-  region: "us-west-2"
-  cost_per_request: "$0.05"
-
-status: "healthy"
-last_heartbeat: "2025-12-04T19:30:00.000Z"
-```
-
----
-
-## 5. Authentication Methods
-
-### 5.1 Mutual TLS (mTLS)
-
-**Recommended for production**. Both client and server authenticate via X.509 certificates.
-
-```yaml
-# Agent manifest with mTLS
-apiVersion: ossa/v0.2.9
-kind: Agent
-metadata:
-  name: secure-agent
-spec:
-  security:
-    authentication:
-      type: mtls
-      certificate:
-        path: /etc/ossa/certs/agent.crt
-        key_path: /etc/ossa/certs/agent.key
-      ca_bundle: /etc/ossa/certs/ca.crt
-      verify_client: true
-```
-
-**Certificate Requirements**:
-- Subject Alternative Name (SAN) MUST include agent URI
-- Common Name (CN) SHOULD be agent name
-- Certificates MUST be valid (not expired)
-- Issuer MUST be trusted CA
-
-**Example Certificate**:
-
-```
-Subject: CN=code-reviewer, O=Acme Corp
-SAN:
-  - URI:agent://team-a/code-reviewer
-  - DNS:code-reviewer.agents.example.com
-Issuer: CN=OSSA CA, O=Acme Corp
-Validity: 2025-01-01 to 2026-01-01
-```
-
-### 5.2 Bearer Token (JWT)
-
-Agents authenticate using JWT bearer tokens.
-
-```yaml
-# Agent manifest with JWT
-apiVersion: ossa/v0.2.9
-kind: Agent
-metadata:
-  name: api-agent
-spec:
-  security:
-    authentication:
-      type: bearer
-      token_source:
-        type: file
-        path: /run/secrets/agent-token
-      issuer: "https://auth.example.com"
-      audience: "ossa-agents"
-```
-
-**JWT Claims**:
-
-```json
-{
-  "iss": "https://auth.example.com",
-  "sub": "agent://team-a/code-reviewer",
-  "aud": "ossa-agents",
-  "exp": 1735939800,
-  "iat": 1735936200,
-  "capabilities": ["code_analysis", "security_scanning"]
-}
-```
-
-**HTTP Request with Bearer Token**:
-
-```http
-POST /agents/code-analyzer/tasks HTTP/1.1
-Host: agents.example.com
-Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
-Content-Type: application/json
-
-{
-  "version": "ossa/a2a/v0.2.9",
-  "from": "agent://team-a/code-reviewer",
-  "to": "agent://team-b/code-analyzer",
-  "payload": {...}
-}
-```
-
-### 5.3 OpenID Connect (OIDC)
-
-Agents use OIDC for federated authentication.
-
-```yaml
-# Agent manifest with OIDC
-apiVersion: ossa/v0.2.9
-kind: Agent
-metadata:
-  name: oidc-agent
-spec:
-  security:
-    authentication:
-      type: oidc
-      provider: "https://accounts.google.com"
-      client_id: "abc123.apps.googleusercontent.com"
-      client_secret:
-        secret_ref:
-          name: oidc-credentials
-          key: client_secret
-      scopes:
-        - openid
-        - profile
-        - ossa.agent
-```
-
-**OIDC Flow**:
-
-1. Agent requests token from provider
-2. Provider returns ID token + access token
-3. Agent includes access token in `Authorization` header
-4. Recipient validates token with provider's public keys
-
----
-
-## 6. Routing Patterns
-
-### 6.1 Direct Routing (Point-to-Point)
-
-Agent A sends message directly to Agent B.
-
-```yaml
-version: "ossa/a2a/v0.2.9"
-id: "msg_abc123"
-timestamp: "2025-12-04T19:30:00.000Z"
-from: "agent://team-a/code-reviewer"
-to: "agent://team-b/code-analyzer"      # Direct recipient
-type: "request"
-correlation_id: "req_xyz789"
-payload:
-  action: "analyze_code"
-  data:
-    repository: "https://github.com/org/repo"
-    commit_sha: "abc123"
-```
-
-**Use Case**: Task delegation, peer-to-peer collaboration
-
-### 6.2 Broadcast Routing (Fan-Out)
-
-Agent A sends message to all agents in a group.
-
-```yaml
-version: "ossa/a2a/v0.2.9"
-id: "msg_broadcast_001"
-timestamp: "2025-12-04T19:30:00.000Z"
-from: "agent://orchestrator/main"
-to: "broadcast://team-a/*"              # All agents in team-a
-type: "event"
-payload:
-  event: "deployment_started"
-  data:
-    version: "v1.2.3"
-    environment: "production"
-```
-
-**Use Case**: Notifications, system-wide announcements
-
-### 6.3 Topic-Based Routing (Pub/Sub)
-
-Agents subscribe to topics and receive matching messages.
-
-```yaml
-# Publisher
-version: "ossa/a2a/v0.2.9"
-id: "msg_topic_001"
-timestamp: "2025-12-04T19:30:00.000Z"
-from: "agent://team-a/code-reviewer"
-to: "topic://code-reviews"              # Topic name
-type: "event"
-payload:
-  event: "review_completed"
-  data:
-    pull_request: "https://github.com/org/repo/pull/42"
-    status: "approved"
-    reviewer: "agent://team-a/code-reviewer"
-```
-
-**Subscription Example**:
-
-```yaml
-# Agent subscribes to topic
-apiVersion: ossa/v0.2.9
-kind: Agent
-metadata:
-  name: notification-agent
-spec:
-  messaging:
-    subscriptions:
-      - topic: "topic://code-reviews"
-        handler: on_code_review
-      - topic: "topic://deployments"
-        handler: on_deployment
-        filter:
-          environment: production
-```
-
-**Use Case**: Event-driven architectures, logging/monitoring
-
-### 6.4 Request/Response Pattern
-
-Agent A sends request, Agent B responds with correlation.
-
-```yaml
-# Request
-version: "ossa/a2a/v0.2.9"
-id: "msg_req_001"
-timestamp: "2025-12-04T19:30:00.000Z"
-from: "agent://team-a/requester"
-to: "agent://team-b/responder"
-type: "request"
-correlation_id: "conv_abc123"
-reply_to: "agent://team-a/requester"
-ttl: 30
-payload:
-  action: "get_analysis"
-  params:
-    file: "src/main.ts"
-
----
-# Response
-version: "ossa/a2a/v0.2.9"
-id: "msg_resp_001"
-timestamp: "2025-12-04T19:30:15.000Z"
-from: "agent://team-b/responder"
-to: "agent://team-a/requester"
-type: "response"
-correlation_id: "conv_abc123"           # Same as request
-payload:
-  status: "success"
-  result:
-    issues: []
-    quality_score: 95
-```
-
-**Use Case**: Synchronous operations, queries
-
----
-
-## 7. Task Lifecycle
-
-When agents collaborate on tasks, they follow a standard lifecycle:
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                      TASK LIFECYCLE                              │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                  │
-│  ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐     │
-│  │SUBMITTED │──▶│ ACCEPTED │──▶│ WORKING  │──▶│COMPLETED │     │
-│  └──────────┘   └──────────┘   └──────────┘   └──────────┘     │
-│       │               │              │              │           │
-│       │               │              │              │           │
-│       │               ▼              ▼              │           │
-│       │         ┌──────────┐   ┌──────────┐        │           │
-│       └────────▶│ REJECTED │   │  FAILED  │◀───────┘           │
-│                 └──────────┘   └──────────┘                     │
-│                                     │                           │
-│                                     ▼                           │
-│                               ┌──────────┐                      │
-│                               │CANCELLED │                      │
-│                               └──────────┘                      │
-│                                                                  │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-### Task States
-
-```typescript
-type TaskState =
-  | 'submitted'   // Task sent to agent
-  | 'accepted'    // Agent acknowledged task
-  | 'rejected'    // Agent declined task
-  | 'working'     // Agent processing task
-  | 'completed'   // Task finished successfully
-  | 'failed'      // Task failed with error
-  | 'cancelled';  // Task cancelled by requester
-
-interface TaskStatus {
-  task_id: string;
-  state: TaskState;
-  progress?: number;          // 0-100
-  message?: string;           // Human-readable status
-  error?: TaskError;
-  started_at?: string;        // ISO 8601
-  completed_at?: string;      // ISO 8601
-}
-
-interface TaskError {
-  code: string;
-  message: string;
-  details?: unknown;
-  recoverable: boolean;
-}
-```
-
-### Task Submission
-
-```yaml
-# Submit task
-version: "ossa/a2a/v0.2.9"
-id: "msg_task_submit_001"
-timestamp: "2025-12-04T19:30:00.000Z"
-from: "agent://team-a/orchestrator"
-to: "agent://team-b/worker"
-type: "request"
-correlation_id: "task_xyz789"
-reply_to: "agent://team-a/orchestrator"
-payload:
-  action: "execute_task"
-  task_id: "task_xyz789"
-  input:
-    operation: "analyze_codebase"
-    parameters:
-      repository: "https://github.com/org/repo"
-      branch: "main"
-```
-
-### Task Acceptance
-
-```yaml
-# Accept task
-version: "ossa/a2a/v0.2.9"
-id: "msg_task_accept_001"
-timestamp: "2025-12-04T19:30:01.000Z"
-from: "agent://team-b/worker"
-to: "agent://team-a/orchestrator"
-type: "response"
-correlation_id: "task_xyz789"
-payload:
-  status: "accepted"
-  task_id: "task_xyz789"
-  estimated_duration_seconds: 120
-```
-
-### Task Progress Updates (Streaming)
-
-```yaml
-# Progress update
-version: "ossa/a2a/v0.2.9"
-id: "msg_task_progress_001"
-timestamp: "2025-12-04T19:30:30.000Z"
-from: "agent://team-b/worker"
-to: "agent://team-a/orchestrator"
-type: "event"
-correlation_id: "task_xyz789"
-payload:
-  event: "task_progress"
-  task_id: "task_xyz789"
-  state: "working"
-  progress: 50
-  message: "Analyzed 150/300 files"
-```
-
-### Task Completion
-
-```yaml
-# Success
-version: "ossa/a2a/v0.2.9"
-id: "msg_task_complete_001"
-timestamp: "2025-12-04T19:32:00.000Z"
-from: "agent://team-b/worker"
-to: "agent://team-a/orchestrator"
-type: "response"
-correlation_id: "task_xyz789"
-payload:
-  status: "completed"
-  task_id: "task_xyz789"
-  result:
-    files_analyzed: 300
-    issues_found: 12
-    quality_score: 87
-
----
-# Failure
-version: "ossa/a2a/v0.2.9"
-id: "msg_task_fail_001"
-timestamp: "2025-12-04T19:31:30.000Z"
-from: "agent://team-b/worker"
-to: "agent://team-a/orchestrator"
-type: "response"
-correlation_id: "task_xyz789"
-payload:
-  status: "failed"
-  task_id: "task_xyz789"
-  error:
-    code: "REPOSITORY_UNREACHABLE"
-    message: "Failed to clone repository"
-    details:
-      url: "https://github.com/org/repo"
-      http_status: 404
-    recoverable: true
-```
-
-### Task Cancellation
-
-```yaml
-# Cancel request
-version: "ossa/a2a/v0.2.9"
-id: "msg_task_cancel_001"
-timestamp: "2025-12-04T19:31:00.000Z"
-from: "agent://team-a/orchestrator"
-to: "agent://team-b/worker"
-type: "command"
-correlation_id: "task_xyz789"
-payload:
-  action: "cancel_task"
-  task_id: "task_xyz789"
-  reason: "User requested cancellation"
-
----
-# Cancel acknowledgment
-version: "ossa/a2a/v0.2.9"
-id: "msg_task_cancelled_001"
-timestamp: "2025-12-04T19:31:01.000Z"
-from: "agent://team-b/worker"
-to: "agent://team-a/orchestrator"
-type: "response"
-correlation_id: "task_xyz789"
-payload:
-  status: "cancelled"
-  task_id: "task_xyz789"
-  partial_result:
-    files_analyzed: 75
-```
-
----
-
-## 8. Error Handling
-
-### A2A Error Codes
-
-```typescript
-type A2AErrorCode =
-  // Addressing Errors
-  | 'AGENT_NOT_FOUND'         // Recipient agent not found
-  | 'AGENT_UNREACHABLE'       // Cannot connect to agent
-  | 'TOPIC_NOT_FOUND'         // Topic doesn't exist
-
-  // Authentication Errors
-  | 'AUTH_REQUIRED'           // Authentication required
-  | 'AUTH_FAILED'             // Authentication failed
-  | 'AUTH_EXPIRED'            // Credentials expired
-  | 'INSUFFICIENT_PERMISSIONS' // Lacks required permissions
-
-  // Message Errors
-  | 'INVALID_MESSAGE'         // Malformed message
-  | 'MESSAGE_EXPIRED'         // TTL exceeded
-  | 'MESSAGE_TOO_LARGE'       // Payload exceeds limit
-
-  // Task Errors
-  | 'TASK_REJECTED'           // Agent rejected task
-  | 'TASK_TIMEOUT'            // Task execution timeout
-  | 'TASK_CANCELLED'          // Task cancelled by requester
-
-  // Protocol Errors
-  | 'UNSUPPORTED_VERSION'     // Protocol version not supported
-  | 'UNSUPPORTED_TRANSPORT'   // Transport not supported
-  | 'RATE_LIMITED';           // Too many requests
-
-interface A2AError {
-  code: A2AErrorCode;
-  message: string;
-  details?: Record<string, unknown>;
-  timestamp: string;
-  retry_after_seconds?: number;
-}
-```
-
-### Error Response
-
-```yaml
-version: "ossa/a2a/v0.2.9"
-id: "msg_error_001"
-timestamp: "2025-12-04T19:30:00.000Z"
-from: "agent://team-b/worker"
-to: "agent://team-a/orchestrator"
-type: "response"
-correlation_id: "task_xyz789"
-payload:
-  status: "error"
-  error:
-    code: "AGENT_UNREACHABLE"
-    message: "Cannot connect to code-analyzer agent"
-    details:
-      target_agent: "agent://team-c/code-analyzer"
-      endpoint: "https://agents.example.com/code-analyzer"
-      network_error: "Connection timeout after 30s"
-    timestamp: "2025-12-04T19:30:00.000Z"
-    retry_after_seconds: 60
-```
-
-### Retry Strategy
-
-```yaml
-# Agent manifest with retry policy
-apiVersion: ossa/v0.2.9
-kind: Agent
-metadata:
-  name: resilient-agent
-spec:
-  messaging:
-    retry:
-      max_attempts: 3
-      backoff: exponential
-      initial_delay_ms: 1000
-      max_delay_ms: 30000
-      retryable_errors:
-        - AGENT_UNREACHABLE
-        - MESSAGE_TIMEOUT
-        - RATE_LIMITED
-```
-
----
-
-## 9. Streaming Support
-
-For long-running tasks, agents can stream progress updates.
-
-### Server-Sent Events (SSE)
-
-```http
-GET /agents/worker/tasks/task_xyz789/stream HTTP/1.1
-Host: agents.example.com
-Accept: text/event-stream
-
-HTTP/1.1 200 OK
-Content-Type: text/event-stream
-Cache-Control: no-cache
-
-event: progress
-data: {"progress": 25, "message": "Analyzing files..."}
-
-event: progress
-data: {"progress": 50, "message": "Running security scan..."}
-
-event: progress
-data: {"progress": 75, "message": "Generating report..."}
-
-event: completed
-data: {"status": "success", "result": {...}}
-```
-
-### WebSocket Streaming
-
-```yaml
-# Connect to task stream
-ws://agents.example.com/agents/worker/tasks/task_xyz789/stream
-
-# Messages from agent
-{
-  "type": "progress",
-  "task_id": "task_xyz789",
-  "progress": 33,
-  "message": "Processing batch 1/3"
-}
-
-{
-  "type": "progress",
-  "task_id": "task_xyz789",
-  "progress": 66,
-  "message": "Processing batch 2/3"
-}
-
-{
-  "type": "completed",
-  "task_id": "task_xyz789",
-  "status": "success",
-  "result": {...}
-}
-```
-
-### gRPC Streaming
-
-```protobuf
-service AgentService {
-  rpc ExecuteTask(TaskRequest) returns (stream TaskUpdate);
-}
-
-message TaskUpdate {
-  string task_id = 1;
-  TaskState state = 2;
-  int32 progress = 3;
-  string message = 4;
-  google.protobuf.Struct result = 5;
-}
-```
-
----
-
-## 10. Push Notifications
-
-Agents can register webhooks to receive push notifications.
-
-### Webhook Registration
-
-```yaml
-# Register webhook
-POST /agents/code-reviewer/webhooks
-Content-Type: application/json
-
-{
-  "url": "https://my-app.example.com/webhooks/agent-events",
-  "events": [
-    "task.completed",
-    "task.failed",
-    "agent.status_changed"
-  ],
-  "authentication": {
-    "type": "bearer",
-    "token": "secret_webhook_token_xyz"
-  },
-  "retry_policy": {
-    "max_attempts": 5,
-    "backoff": "exponential"
-  }
-}
-```
-
-### Webhook Delivery
-
-```http
-POST /webhooks/agent-events HTTP/1.1
-Host: my-app.example.com
-Content-Type: application/json
-X-OSSA-Event: task.completed
-X-OSSA-Signature: sha256=abc123...
-X-OSSA-Delivery: delivery_001
-
-{
-  "version": "ossa/a2a/v0.2.9",
-  "id": "event_webhook_001",
-  "timestamp": "2025-12-04T19:32:00.000Z",
-  "from": "agent://team-b/worker",
-  "event": "task.completed",
-  "payload": {
-    "task_id": "task_xyz789",
-    "status": "completed",
-    "result": {...}
-  }
-}
-```
-
-**Webhook Verification**:
-
-```python
-import hmac
-import hashlib
-
-def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
-    expected = "sha256=" + hmac.new(
-        secret.encode(),
-        payload,
-        hashlib.sha256
-    ).hexdigest()
-    return hmac.compare_digest(expected, signature)
-```
-
----
-
-## 11. Transport Bindings
-
-### 11.1 HTTP/REST Binding
-
-```http
-POST /agents/{agent_name}/messages HTTP/1.1
-Host: agents.example.com
-Content-Type: application/json
-Authorization: Bearer {token}
-
-{
-  "version": "ossa/a2a/v0.2.9",
-  "id": "msg_abc123",
-  "from": "agent://sender",
-  "to": "agent://receiver",
-  "type": "request",
-  "payload": {...}
-}
-
----
-HTTP/1.1 202 Accepted
-Content-Type: application/json
-
-{
-  "message_id": "msg_abc123",
-  "status": "accepted",
-  "timestamp": "2025-12-04T19:30:00.000Z"
-}
-```
-
-### 11.2 gRPC Binding
-
-```protobuf
-service AgentMessaging {
-  rpc SendMessage(A2AMessage) returns (MessageAck);
-  rpc StreamMessages(StreamRequest) returns (stream A2AMessage);
-}
-
-message A2AMessage {
-  string version = 1;
-  string id = 2;
-  google.protobuf.Timestamp timestamp = 3;
-  string from = 4;
-  string to = 5;
-  string correlation_id = 6;
-  MessageType type = 7;
-  google.protobuf.Struct payload = 8;
-}
-```
-
-### 11.3 MQTT Binding
-
-```yaml
-# Publish to agent topic
-Topic: ossa/agents/code-reviewer/messages
-QoS: 1
-Retain: false
-
-Payload:
-  version: "ossa/a2a/v0.2.9"
-  id: "msg_mqtt_001"
-  from: "agent://sender"
-  to: "agent://code-reviewer"
-  type: "request"
-  payload: {...}
-```
-
----
-
-## 12. Observability
-
-### W3C Trace Context Propagation
-
-All A2A messages MUST propagate W3C trace context.
-
-```yaml
-version: "ossa/a2a/v0.2.9"
-id: "msg_abc123"
-timestamp: "2025-12-04T19:30:00.000Z"
-from: "agent://team-a/orchestrator"
-to: "agent://team-b/worker"
-type: "request"
-trace_context:
-  traceparent: "00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"
-  tracestate: "vendor=value"
-payload:
-  action: "execute_task"
-```
-
-**HTTP Headers**:
-
-```http
-POST /agents/worker/messages HTTP/1.1
-traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
-tracestate: vendor=value
-```
-
-### OpenTelemetry Spans
-
-```typescript
-// Sender creates span
-const span = tracer.startSpan('a2a.send_message', {
-  attributes: {
-    'a2a.message_id': 'msg_abc123',
-    'a2a.from': 'agent://team-a/orchestrator',
-    'a2a.to': 'agent://team-b/worker',
-    'a2a.type': 'request',
-    'a2a.correlation_id': 'task_xyz789'
-  }
-});
-
-// Receiver continues trace
-const receiverSpan = tracer.startSpan('a2a.receive_message', {
-  parent: extractedContext,
-  attributes: {
-    'a2a.message_id': 'msg_abc123',
-    'a2a.processing_time_ms': 1234
-  }
-});
-```
-
----
-
-## 13. Security Considerations
-
-### Message Signing
-
-Messages SHOULD be signed to prevent tampering.
-
-```yaml
-version: "ossa/a2a/v0.2.9"
-id: "msg_signed_001"
-timestamp: "2025-12-04T19:30:00.000Z"
-from: "agent://team-a/sender"
-to: "agent://team-b/receiver"
-type: "request"
-payload: {...}
-signature:
-  algorithm: "RS256"
-  keyid: "key_abc123"
-  value: "base64_signature_here..."
-```
-
-### Message Encryption
-
-Sensitive payloads SHOULD be encrypted.
-
-```yaml
-version: "ossa/a2a/v0.2.9"
-id: "msg_encrypted_001"
-timestamp: "2025-12-04T19:30:00.000Z"
-from: "agent://team-a/sender"
-to: "agent://team-b/receiver"
-type: "request"
-payload_encrypted: true
-encryption:
-  algorithm: "AES-256-GCM"
-  key_id: "key_xyz789"
-  nonce: "base64_nonce..."
-payload: "base64_encrypted_payload..."
-```
-
-### Rate Limiting
-
-```yaml
-# Agent manifest with rate limiting
-apiVersion: ossa/v0.2.9
-kind: Agent
-metadata:
-  name: rate-limited-agent
-spec:
-  messaging:
-    rate_limits:
-      - type: per_sender
-        requests_per_minute: 60
-      - type: global
-        requests_per_minute: 1000
-      - type: per_topic
-        topic: "topic://high-priority"
-        requests_per_minute: 10
-```
-
----
-
-## 14. Compliance Requirements
-
-### MUST Requirements
-
-1. Messages MUST include `version`, `id`, `timestamp`, `from`, `to`, `type`, `payload`
-2. Agent URIs MUST follow format: `agent://{namespace}/{name}`
-3. Timestamps MUST be ISO 8601 format with timezone
-4. Message IDs MUST be globally unique (UUID recommended)
-5. Correlation IDs MUST match across request/response pairs
-6. TTL MUST be honored; expired messages MUST be dropped
-7. Authentication MUST be enforced in production environments
-8. TLS 1.3+ MUST be used for HTTP/gRPC transports
-
-### SHOULD Requirements
-
-1. Agents SHOULD publish AgentCard on startup
-2. Agents SHOULD implement at least one discovery method
-3. Agents SHOULD propagate W3C trace context
-4. Agents SHOULD sign messages in untrusted networks
-5. Agents SHOULD implement exponential backoff for retries
-6. Agents SHOULD emit OpenTelemetry spans for all messages
-
-### MAY Requirements
-
-1. Agents MAY support multiple transports
-2. Agents MAY implement custom routing logic
-3. Agents MAY encrypt message payloads
-4. Agents MAY implement priority queuing
-
----
-
-## 15. Examples
-
-### Example 1: Code Review Workflow
-
-```yaml
-# 1. Developer agent requests code review
-version: "ossa/a2a/v0.2.9"
-id: "msg_001"
-timestamp: "2025-12-04T19:30:00.000Z"
-from: "agent://dev/alice-assistant"
-to: "agent://code-review/reviewer"
-type: "request"
-correlation_id: "review_pr_42"
-reply_to: "agent://dev/alice-assistant"
-payload:
-  action: "review_code"
-  pull_request: "https://github.com/org/repo/pull/42"
-  focus_areas: ["security", "performance"]
-
----
-# 2. Reviewer accepts task
-version: "ossa/a2a/v0.2.9"
-id: "msg_002"
-timestamp: "2025-12-04T19:30:01.000Z"
-from: "agent://code-review/reviewer"
-to: "agent://dev/alice-assistant"
-type: "response"
-correlation_id: "review_pr_42"
-payload:
-  status: "accepted"
-  estimated_duration_seconds: 180
-
----
-# 3. Reviewer sends progress
-version: "ossa/a2a/v0.2.9"
-id: "msg_003"
-timestamp: "2025-12-04T19:31:00.000Z"
-from: "agent://code-review/reviewer"
-to: "agent://dev/alice-assistant"
-type: "event"
-correlation_id: "review_pr_42"
-payload:
-  event: "progress"
-  progress: 50
-  message: "Completed security scan, running performance tests"
-
----
-# 4. Reviewer completes review
-version: "ossa/a2a/v0.2.9"
-id: "msg_004"
-timestamp: "2025-12-04T19:33:00.000Z"
-from: "agent://code-review/reviewer"
-to: "agent://dev/alice-assistant"
-type: "response"
-correlation_id: "review_pr_42"
-payload:
-  status: "completed"
-  result:
-    overall_score: 85
-    security_issues: 2
-    performance_concerns: 1
-    recommendation: "approve_with_changes"
-    comments:
-      - line: 42
-        message: "Consider using parameterized query to prevent SQL injection"
-```
-
-### Example 2: Multi-Agent Orchestration
-
-```yaml
-# Orchestrator broadcasts task to worker pool
-version: "ossa/a2a/v0.2.9"
-id: "msg_orchestrator_001"
-timestamp: "2025-12-04T19:30:00.000Z"
-from: "agent://orchestrator/main"
-to: "broadcast://workers/*"
-type: "request"
-correlation_id: "batch_job_123"
-reply_to: "agent://orchestrator/main"
-payload:
-  action: "claim_task"
-  task_pool: "image_processing"
-  max_workers: 5
-
----
-# Worker claims task
-version: "ossa/a2a/v0.2.9"
-id: "msg_worker_001"
-timestamp: "2025-12-04T19:30:01.000Z"
-from: "agent://workers/worker-01"
-to: "agent://orchestrator/main"
-type: "response"
-correlation_id: "batch_job_123"
-payload:
-  status: "claimed"
-  worker_id: "worker-01"
-  capacity: 10
-
----
-# Orchestrator assigns task
-version: "ossa/a2a/v0.2.9"
-id: "msg_orchestrator_002"
-timestamp: "2025-12-04T19:30:02.000Z"
-from: "agent://orchestrator/main"
-to: "agent://workers/worker-01"
-type: "request"
-correlation_id: "task_img_001"
-payload:
-  action: "process_images"
-  images:
-    - "s3://bucket/img1.jpg"
-    - "s3://bucket/img2.jpg"
-  operations: ["resize", "optimize", "watermark"]
-```
-
----
-
-## References
-
-- [OSSA Schema v0.2.9](./ossa-0.2.9.schema.json)
-- [Runtime Semantics](./runtime-semantics.md)
-- [Semantic Conventions](./semantic-conventions.md)
-- [Google A2A Protocol (2024)](https://github.com/google/a2a-protocol)
-- [W3C Trace Context](https://www.w3.org/TR/trace-context/)
-- [CloudEvents Specification](https://cloudevents.io/)
-- [OpenTelemetry Specification](https://opentelemetry.io/docs/specs/)
-- [RFC 6763: DNS-Based Service Discovery](https://tools.ietf.org/html/rfc6763)