feat(agent): add forward-compatible response parsing

Author: nkavian

README.md

@@ -252,6 +252,10 @@ its Actions can advertise enrollment, payment, and trust protocols, but ODP does
 credentials, invoke Actions, submit payments, or implement trust protocols. Applications compose
 the appropriate protocol clients around an Action resolved through ODP.
 
+`parse_service_document` is the strict current-version Service parser. Agent inspection and
+Directory results filter unrecognized enrollment, payment, and trust descriptors while retaining
+strict validation for recognized descriptors.
+
 ## Errors and validation
 
 Each role exposes typed errors:

scripts/conformance_adapter.py

@@ -17,20 +17,26 @@
     Page,
     derive_service_origin,
     is_local_resource_identifier,
+    parse_agent_service_document,
     parse_collection,
+    parse_collection_page,
     parse_collection_search_request,
     parse_filter_definition,
+    parse_filter_definition_page,
     parse_offering,
     parse_offering_page,
     parse_offering_search_request,
+    parse_problem_details,
     parse_problem_response,
     parse_resource_identity,
     parse_service_document,
     parse_sort_definition,
+    parse_sort_definition_page,
     resolve_continuation,
     resolve_resource_reference,
     validate_value,
 )
+from offering_protocol.core.validation import _normalize_agent_response
 from offering_protocol.directory.transport import HttpRequest, HttpResponse
 from offering_protocol.service import CatalogRequest, Request, ServiceBuilder
 
@@ -265,6 +271,25 @@ async def evaluate_case(subject: str, case: dict[str, Any], role: str) -> bool |
             succeeds(lambda: parse_collection_search_request(json.dumps(case["request"])))
             == case["valid"]
         )
+    if subject == "composition-contract":
+        if case.get("operation") == "normalize-agent-response" and role == "agent":
+            normalized = _normalize_agent_response(case["document"], case["kind"])
+            _parse_agent_response(normalized, case["kind"])
+            return normalized == case["expected"]
+        if case.get("operation") == "validate-advertisement":
+            document = _service_document_with_protocols(case["protocols"])
+            return succeeds(lambda: parse_service_document(json.dumps(document))) == case["valid"]
+        if case.get("operation") == "filter-advertisement" and role == "agent":
+            document = parse_agent_service_document(
+                json.dumps(_service_document_with_protocols(case["protocols"]))
+            )
+            actual = (
+                document.protocols.model_dump(mode="json", exclude_defaults=True)
+                if document.protocols is not None
+                else {}
+            )
+            return actual == case["expected"]
+        return None
     if subject == "offering-search-contract" and case.get("operation") == "validate-request":
         return (
             succeeds(lambda: parse_offering_search_request(json.dumps(case["request"])))
@@ -308,6 +333,40 @@ async def evaluate_case(subject: str, case: dict[str, Any], role: str) -> bool |
     return None
 
 
+def _parse_agent_response(document: dict[str, Any], kind: str) -> object:
+    encoded = json.dumps(document, separators=(",", ":"))
+    parsers: dict[str, Callable[[str], object]] = {
+        "service-document": parse_agent_service_document,
+        "collection": parse_collection,
+        "offering": parse_offering,
+        "collection-page": parse_collection_page,
+        "offering-page": parse_offering_page,
+        "filter-page": parse_filter_definition_page,
+        "sort-page": parse_sort_definition_page,
+        "problem": parse_problem_details,
+    }
+    parser = parsers.get(kind)
+    if parser is None:
+        raise ValueError("Unknown Agent response kind")
+    return parser(encoded)
+
+
+def _service_document_with_protocols(protocols: object) -> dict[str, object]:
+    return {
+        "description": "ODP Python conformance adapter",
+        "http": {"endpoint_base": "/odp"},
+        "language": "en",
+        "localizations": ["en"],
+        "name": "Conformance Service",
+        "odp_version": "1.0",
+        "operations": [
+            {"authentication": "not-required", "name": "get-offering"},
+            {"authentication": "not-required", "name": "list-offerings"},
+        ],
+        "protocols": protocols,
+    }
+
+
 async def evaluate(request: dict[str, Any]) -> dict[str, object]:
     try:
         actual = await evaluate_case(request["vector"]["subject"], request["case"], request["role"])

src/offering_protocol/agent/client.py

@@ -21,18 +21,30 @@
     OfferingSearchRequest,
     Operation,
     Page,
+    ProblemDetails,
     Representation,
     ServiceDocument,
     build_operation_url,
     derive_service_origin,
-    parse_collection,
-    parse_collection_page,
-    parse_offering,
-    parse_offering_page,
-    parse_problem_response,
-    parse_service_document,
+    parse_agent_service_document,
     resolve_continuation,
 )
+from offering_protocol.core import (
+    parse_collection as parse_collection_strict,
+)
+from offering_protocol.core import (
+    parse_collection_page as parse_collection_page_strict,
+)
+from offering_protocol.core import (
+    parse_offering as parse_offering_strict,
+)
+from offering_protocol.core import (
+    parse_offering_page as parse_offering_page_strict,
+)
+from offering_protocol.core import (
+    parse_problem_response as parse_problem_response_strict,
+)
+from offering_protocol.core.validation import _normalize_agent_response
 from offering_protocol.directory.transport import (
     HttpRequest,
     HttpResponse,
@@ -136,10 +148,10 @@ async def inspect(self) -> Inspection:
             b"",
             _MAXIMUM_DOCUMENT_BYTES,
             self._cache_fallbacks.service_document,
-            parse_service_document,
+            parse_agent_service_document,
         )
         return Inspection(
-            document=parse_service_document(response.body),
+            document=parse_agent_service_document(response.body),
             final_url=response.final_url,
             freshness=response.freshness,
             requested_url=requested_url,
@@ -571,6 +583,33 @@ def _operation_parser(operation: Operation) -> object:
     return parse_offering_page
 
 
+def parse_collection(data: bytes | str) -> Collection:
+    return parse_collection_strict(_normalize_body(data, "collection"))
+
+
+def parse_offering(data: bytes | str) -> Offering:
+    return parse_offering_strict(_normalize_body(data, "offering"))
+
+
+def parse_collection_page(data: bytes | str) -> Page[Collection]:
+    return parse_collection_page_strict(_normalize_body(data, "collection-page"))
+
+
+def parse_offering_page(data: bytes | str) -> OfferingPage[Offering]:
+    return parse_offering_page_strict(_normalize_body(data, "offering-page"))
+
+
+def parse_problem_response(data: bytes | str, status: int) -> ProblemDetails:
+    return parse_problem_response_strict(_normalize_body(data, "problem"), status)
+
+
+def _normalize_body(data: bytes | str, kind: str) -> str:
+    raw = json.loads(data)
+    if not isinstance(raw, dict):
+        return data.decode() if isinstance(data, bytes) else data
+    return json.dumps(_normalize_agent_response(raw, kind), separators=(",", ":"))
+
+
 def _encode(value: object) -> bytes:
     if not hasattr(value, "model_dump_json"):
         raise TypeError("ODP model is not serializable")

src/offering_protocol/agent/details.py

@@ -53,7 +53,7 @@ class DiscoveredAction:
     http: DiscoveredHttpAction | None
     id: str
     openapi: DiscoveredOpenApiAction | None
-    rel: ActionRelation
+    rel: ActionRelation | str
 
 
 @dataclass(frozen=True, slots=True)

src/offering_protocol/core/__init__.py

@@ -16,6 +16,7 @@
 from offering_protocol.core.validation import (
     OdpValidationError,
     ValidationIssue,
+    parse_agent_service_document,
     parse_collection,
     parse_collection_page,
     parse_collection_search_request,
@@ -44,6 +45,7 @@
     "is_local_resource_identifier",
     "operation_method",
     "operation_path",
+    "parse_agent_service_document",
     "parse_collection",
     "parse_collection_page",
     "parse_collection_search_request",

src/offering_protocol/core/models.py

@@ -379,7 +379,7 @@ class Action(OdpModel):
     http: HttpActionTarget | None = None
     id: str
     openapi: OpenApiActionTarget | None = None
-    rel: ActionRelation
+    rel: ActionRelation | str
 
 
 class Offering(OdpModel):