adcontextprotocol
diff --git a/‎src/adapters/mock_ad_server.py‎
Lines changed: 2 additions & 5 deletions b/‎src/adapters/mock_ad_server.py‎
Lines changed: 2 additions & 5 deletions
diff --git a/‎src/core/main.py‎
Lines changed: 20 additions & 47 deletions b/‎src/core/main.py‎
Lines changed: 20 additions & 47 deletions
diff --git a/‎src/core/protocol_envelope.py‎
Lines changed: 172 additions & 0 deletions b/‎src/core/protocol_envelope.py‎
Lines changed: 172 additions & 0 deletions
@@ -399,8 +399,6 @@ def create_media_buy(
             if scenario.should_ask_question:
                 return CreateMediaBuyResponse(
                     media_buy_id=f"pending_question_{id(request)}",
-                    status="pending",
-                    message=scenario.question_text or "Additional information needed",
                     creative_deadline=None,
                     buyer_ref=request.buyer_ref,
                 )
@@ -510,9 +508,8 @@ def _create_media_buy_async(
 
         # Return pending response
         return CreateMediaBuyResponse(
+            buyer_ref=request.buyer_ref,
             media_buy_id=f"pending_{step.step_id}",
-            status="submitted",
-            message=f"Media buy submitted for processing. Task ID: {step.step_id}",
             creative_deadline=None,
         )
 
@@ -706,10 +703,10 @@ def _create_media_buy_immediate(
             self.log(f"Would return: Campaign ID '{media_buy_id}' with status 'pending_creative'")
 
         return CreateMediaBuyResponse(
-            status="completed",  # Mock adapter completes immediately
             buyer_ref=request.buyer_ref,  # Required field per AdCP spec
             media_buy_id=media_buy_id,
             creative_deadline=datetime.now(UTC) + timedelta(days=2),
+            errors=None,  # No errors for successful mock response
         )
 
     def add_creative_assets(
 
@@ -2463,23 +2463,9 @@ def _sync_creatives_impl(
     if creatives_needing_approval:
         message += f", {len(creatives_needing_approval)} require approval"
 
-    # Build AdCP-compliant response
-    from src.core.schemas import SyncSummary
-
-    total_processed = created_count + updated_count + unchanged_count + failed_count
-
+    # Build AdCP-compliant response (per official spec)
     return SyncCreativesResponse(
-        message=message,
-        status="completed",
-        summary=SyncSummary(
-            total_processed=total_processed,
-            created=created_count,
-            updated=updated_count,
-            unchanged=unchanged_count,
-            failed=failed_count,
-            deleted=0,
-        ),
-        results=results,
+        creatives=results,
         dry_run=dry_run,
     )
 
@@ -3039,7 +3025,7 @@ async def get_signals(req: GetSignalsRequest, context: Context = None) -> GetSig
     # Generate context_id (required field)
     context_id = f"signals_{uuid.uuid4().hex[:12]}"
 
-    return GetSignalsResponse(signals=signals, message=message, context_id=context_id)
+    return GetSignalsResponse(signals=signals)
 
 
 @mcp.tool()
@@ -3111,31 +3097,31 @@ async def activate_signal(
         # Log activity
         log_tool_activity(context, "activate_signal", start_time)
 
-        # Build response with only adapter schema fields - use explicit fields for validator
-        if status == "processing":
-            return ActivateSignalResponse(
-                task_id=task_id,
-                status=status,
-                estimated_activation_duration_minutes=estimated_activation_duration_minutes,
-                decisioning_platform_segment_id=decisioning_platform_segment_id,
-            )
-        elif requires_approval or not activation_success:
+        # Build response with domain data only (protocol fields added by transport layer)
+        activation_details = {}
+        if estimated_activation_duration_minutes:
+            activation_details["estimated_duration_minutes"] = estimated_activation_duration_minutes
+        if decisioning_platform_segment_id:
+            activation_details["platform_segment_id"] = decisioning_platform_segment_id
+        if requires_approval:
+            activation_details["requires_approval"] = True
+
+        if requires_approval or not activation_success:
             return ActivateSignalResponse(
-                task_id=task_id,
-                status=status,
+                signal_id=signal_id,
+                activation_details=activation_details if activation_details else None,
                 errors=errors,
             )
         else:
             return ActivateSignalResponse(
-                task_id=task_id,
-                status=status,
+                signal_id=signal_id,
+                activation_details=activation_details if activation_details else None,
             )
 
     except Exception as e:
         logger.error(f"Error activating signal {signal_id}: {e}")
         return ActivateSignalResponse(
-            task_id=f"task_{uuid.uuid4().hex[:12]}",
-            status="failed",
+            signal_id=signal_id,
             errors=[{"code": "ACTIVATION_ERROR", "message": str(e)}],
         )
 
@@ -3940,9 +3926,8 @@ def _create_media_buy_impl(
         # Update workflow step as failed
         ctx_manager.update_workflow_step(step.step_id, status="failed", error_message=str(e))
 
-        # Return proper error response per AdCP spec (status=failed for validation errors)
+        # Return error response (protocol layer will add status="failed")
         return CreateMediaBuyResponse(
-            status="failed",  # AdCP spec: failed status for execution errors
             buyer_ref=buyer_ref or "unknown",
             errors=[Error(code="validation_error", message=str(e), details=None)],
         )
@@ -3953,7 +3938,6 @@ def _create_media_buy_impl(
         error_msg = f"Principal {principal_id} not found"
         ctx_manager.update_workflow_step(step.step_id, status="failed", error_message=error_msg)
         return CreateMediaBuyResponse(
-            status="rejected",  # AdCP spec: rejected status for auth failures before execution
             buyer_ref=buyer_ref or "unknown",
             errors=[Error(code="authentication_error", message=error_msg, details=None)],
         )
@@ -4029,7 +4013,6 @@ def _create_media_buy_impl(
             return CreateMediaBuyResponse(
                 buyer_ref=req.buyer_ref,
                 media_buy_id=pending_media_buy_id,
-                status=TaskStatus.INPUT_REQUIRED,
                 creative_deadline=None,
                 errors=[{"code": "APPROVAL_REQUIRED", "message": response_msg}],
             )
@@ -4083,7 +4066,6 @@ def _create_media_buy_impl(
                 ctx_manager.update_workflow_step(step.step_id, status="failed", error_message=error_detail)
                 return CreateMediaBuyResponse(
                     buyer_ref=req.buyer_ref,
-                    status=TaskStatus.FAILED,
                     errors=[{"code": "invalid_configuration", "message": err} for err in config_errors],
                 )
 
@@ -4149,9 +4131,7 @@ def _create_media_buy_impl(
                 console.print(f"[yellow]⚠️ Failed to send configuration approval Slack notification: {e}[/yellow]")
 
             return CreateMediaBuyResponse(
-                status="input-required",
                 buyer_ref=req.buyer_ref,
-                task_id=step.step_id,
                 workflow_step_id=step.step_id,
             )
 
@@ -4187,7 +4167,6 @@ def _create_media_buy_impl(
             error_msg = "start_time and end_time are required but were not properly set"
             ctx_manager.update_workflow_step(step.step_id, status="failed", error_message=error_msg)
             return CreateMediaBuyResponse(
-                status="failed",  # AdCP spec: failed status for validation errors
                 buyer_ref=req.buyer_ref,
                 errors=[Error(code="invalid_datetime", message=error_msg, details=None)],
             )
@@ -4382,18 +4361,14 @@ def _create_media_buy_impl(
             }
             response_packages.append(response_package)
 
-        # Create AdCP v2.4 compliant response
-        # Use adapter's status if provided, otherwise calculate based on flight dates
-        api_status = response.status if response.status else media_buy_status
-
         # Ensure buyer_ref is set (defensive check)
         buyer_ref_value = req.buyer_ref if req.buyer_ref else buyer_ref
         if not buyer_ref_value:
             logger.error(f"🚨 buyer_ref is missing! req.buyer_ref={req.buyer_ref}, buyer_ref={buyer_ref}")
             buyer_ref_value = f"missing-{response.media_buy_id}"
 
+        # Create AdCP response (protocol fields like status are added by ProtocolEnvelope wrapper)
         adcp_response = CreateMediaBuyResponse(
-            status=api_status,  # Use adapter status or time-based status (not hardcoded "working")
             buyer_ref=buyer_ref_value,
             media_buy_id=response.media_buy_id,
             packages=response_packages,
@@ -4481,9 +4456,7 @@ def _create_media_buy_impl(
 
         # Use explicit fields for validator (instead of **kwargs)
         modified_response = CreateMediaBuyResponse(
-            status=filtered_data["status"],
             buyer_ref=filtered_data["buyer_ref"],
-            task_id=filtered_data.get("task_id"),
             media_buy_id=filtered_data.get("media_buy_id"),
             creative_deadline=filtered_data.get("creative_deadline"),
             packages=filtered_data.get("packages"),
 
@@ -0,0 +1,172 @@
+"""Protocol envelope wrapper for AdCP responses per AdCP v2.4 spec.
+
+This module implements the protocol envelope pattern defined in:
+https://adcontextprotocol.org/schemas/v1/core/protocol-envelope.json
+
+The envelope separates protocol-level concerns (status, task_id, context_id, message)
+from domain response data (payload). This allows the same domain response models to work
+across different transport layers (MCP, A2A, REST) without embedding protocol fields
+in business logic.
+
+Architecture:
+    Protocol Envelope (added by transport layer)
+    ├── status: Task execution state
+    ├── message: Human-readable summary
+    ├── task_id: Async operation tracking
+    ├── context_id: Session/conversation tracking
+    ├── timestamp: Response generation time
+    ├── push_notification_config: Webhook configuration (optional)
+    └── payload: Domain-specific response data (from schemas.py models)
+
+Usage:
+    # In MCP tool:
+    domain_response = CreateMediaBuyResponse(buyer_ref="...", packages=[...])
+    envelope = ProtocolEnvelope.wrap(
+        payload=domain_response,
+        status="completed",
+        message="Media buy created successfully"
+    )
+
+    # In A2A handler:
+    envelope = ProtocolEnvelope.wrap(
+        payload=get_products_response,
+        status="completed",
+        context_id=conversation_id
+    )
+"""
+
+from datetime import UTC, datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+from src.core.schemas import AdCPBaseModel
+
+# Task status values per AdCP spec
+TaskStatus = Literal[
+    "submitted",  # Task queued for async processing
+    "working",  # Task in progress (< 120s, supports streaming)
+    "completed",  # Task finished successfully
+    "failed",  # Task failed with errors
+    "input-required",  # Task needs user input to proceed
+    "canceled",  # Task canceled by user
+    "rejected",  # Task rejected before starting
+    "auth-required",  # Task needs authentication/authorization
+]
+
+
+class ProtocolEnvelope(BaseModel):
+    """Protocol envelope for AdCP task responses.
+
+    This envelope is added by the protocol layer (MCP, A2A, REST) and wraps
+    task-specific response payloads. Task response schemas should NOT include
+    these fields - they are protocol-level concerns.
+
+    Per AdCP v2.4 spec: /schemas/v1/core/protocol-envelope.json
+    """
+
+    # Required fields
+    status: TaskStatus = Field(
+        ...,
+        description="Current task execution state. Indicates whether the task is completed, "
+        "in progress (working), submitted for async processing, failed, or requires user input.",
+    )
+
+    payload: dict[str, Any] = Field(
+        ...,
+        description="The actual task-specific response data. Contains only domain-specific "
+        "data without protocol-level fields.",
+    )
+
+    # Optional fields
+    context_id: str | None = Field(
+        None,
+        description="Session/conversation identifier for tracking related operations across "
+        "multiple task invocations. Managed by the protocol layer.",
+    )
+
+    task_id: str | None = Field(
+        None,
+        description="Unique identifier for tracking asynchronous operations. Present when a task "
+        "requires extended processing time. Used to query task status and retrieve results.",
+    )
+
+    message: str | None = Field(
+        None,
+        description="Human-readable summary of the task result. Provides natural language "
+        "explanation suitable for display to end users or for AI agent comprehension.",
+    )
+
+    timestamp: datetime | None = Field(
+        None,
+        description="ISO 8601 timestamp when the response was generated. Useful for debugging, "
+        "logging, cache validation, and tracking async operation progress.",
+    )
+
+    push_notification_config: dict[str, Any] | None = Field(
+        None,
+        description="Push notification configuration for async task updates (A2A and REST protocols). "
+        "Echoed from the request to confirm webhook settings.",
+    )
+
+    @classmethod
+    def wrap(
+        cls,
+        payload: AdCPBaseModel | dict[str, Any],
+        status: TaskStatus,
+        message: str | None = None,
+        task_id: str | None = None,
+        context_id: str | None = None,
+        push_notification_config: dict[str, Any] | None = None,
+        add_timestamp: bool = True,
+    ) -> "ProtocolEnvelope":
+        """Wrap a domain response in a protocol envelope.
+
+        Args:
+            payload: Domain-specific response (Pydantic model or dict)
+            status: Task execution status
+            message: Human-readable result summary (optional, generated from payload if not provided)
+            task_id: Async operation tracking ID (optional)
+            context_id: Session/conversation ID (optional)
+            push_notification_config: Webhook configuration (optional)
+            add_timestamp: Whether to add current timestamp (default: True)
+
+        Returns:
+            ProtocolEnvelope wrapping the payload
+
+        Example:
+            >>> response = CreateMediaBuyResponse(buyer_ref="ref123", packages=[...])
+            >>> envelope = ProtocolEnvelope.wrap(
+            ...     payload=response,
+            ...     status="completed",
+            ...     message="Media buy created successfully"
+            ... )
+        """
+        # Convert Pydantic model to dict (using model_dump to exclude internal fields)
+        if isinstance(payload, AdCPBaseModel):
+            payload_dict = payload.model_dump()
+            # Generate message from __str__ if not provided
+            if message is None and hasattr(payload, "__str__"):
+                message = str(payload)
+        else:
+            payload_dict = payload
+
+        # Add timestamp
+        timestamp = datetime.now(UTC) if add_timestamp else None
+
+        return cls(
+            status=status,
+            payload=payload_dict,
+            message=message,
+            task_id=task_id,
+            context_id=context_id,
+            timestamp=timestamp,
+            push_notification_config=push_notification_config,
+        )
+
+    def model_dump(self, **kwargs) -> dict[str, Any]:
+        """Dump envelope to dict, excluding None values by default."""
+        # Exclude None values for cleaner JSON output
+        if "exclude_none" not in kwargs:
+            kwargs["exclude_none"] = True
+        return super().model_dump(**kwargs)