feat(sdk): preserve response-body fields on AgentScoreError + accept identity hints on create_session

Python parity with the same node-sdk additions (commit 75ba394 in node-sdk).
Two non-breaking surface extensions:

1. AgentScoreError grows a ``details: dict[str, Any]`` field populated from
   non-``error`` keys of the response body. Consumers can branch on
   ``verify_url``, ``linked_wallets``, ``claimed_operator``, ``actual_signer``,
   ``reasons``, etc. for granular denial recovery — previously the SDK
   dropped them and only surfaced ``code`` + ``message``. Defaults to ``{}``
   so existing constructor calls keep working.

2. ``create_session`` / ``acreate_session`` accept optional ``address`` +
   ``operator_token`` so a session can be pre-associated with a known wallet
   or be a KYC refresh for an existing ``opc_...``. The ``/v1/sessions`` API
   has accepted these all along; the SDK was just not forwarding them.

Coverage stays at 97.41% (Tier A bar 95%). 146 tests pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: vvillait88

agentscore/client.py

@@ -113,11 +113,16 @@ def _handle_response(self, response: httpx.Response) -> Any:
         if response.status_code >= 400:
             try:
                 body = response.json()
-                error = body.get("error", {})
+                error = body.get("error", {}) if isinstance(body, dict) else {}
+                # Preserve everything except the parsed `error` block so consumers
+                # can read verify_url, linked_wallets, reasons, etc. for granular
+                # denial recovery — mirrors node-sdk's AgentScoreError.details.
+                details = {k: v for k, v in body.items() if k != "error"} if isinstance(body, dict) else {}
                 raise AgentScoreError(
                     code=error.get("code", "unknown_error"),
                     message=error.get("message", response.text),
                     status_code=response.status_code,
+                    details=details,
                 )
             except ValueError as err:
                 raise AgentScoreError(
@@ -171,13 +176,24 @@ def create_session(
         self,
         context: str | None = None,
         product_name: str | None = None,
+        address: str | None = None,
+        operator_token: str | None = None,
     ) -> SessionCreateResponse:
-        """Create an assessment session for deferred scoring."""
+        """Create an assessment session for deferred scoring.
+
+        ``address`` pre-associates the session with a known wallet (EVM ``0x...`` or
+        Solana base58). ``operator_token`` pre-associates with an existing ``opc_...`` —
+        e.g. refresh KYC for a credential.
+        """
         body: dict[str, Any] = {}
         if context is not None:
             body["context"] = context
         if product_name is not None:
             body["product_name"] = product_name
+        if address is not None:
+            body["address"] = address
+        if operator_token is not None:
+            body["operator_token"] = operator_token
         client = self._get_sync_client()
         return self._send_sync(lambda: client.post("/v1/sessions", json=body))
 
@@ -286,13 +302,24 @@ async def acreate_session(
         self,
         context: str | None = None,
         product_name: str | None = None,
+        address: str | None = None,
+        operator_token: str | None = None,
     ) -> SessionCreateResponse:
-        """Create an assessment session for deferred scoring."""
+        """Create an assessment session for deferred scoring.
+
+        ``address`` pre-associates the session with a known wallet (EVM ``0x...`` or
+        Solana base58). ``operator_token`` pre-associates with an existing ``opc_...`` —
+        e.g. refresh KYC for a credential.
+        """
         body: dict[str, Any] = {}
         if context is not None:
             body["context"] = context
         if product_name is not None:
             body["product_name"] = product_name
+        if address is not None:
+            body["address"] = address
+        if operator_token is not None:
+            body["operator_token"] = operator_token
         client = self._get_async_client()
         return await self._send_async(lambda: client.post("/v1/sessions", json=body))
 

agentscore/errors.py

@@ -1,8 +1,23 @@
+from typing import Any
+
+
 class AgentScoreError(Exception):
-    def __init__(self, code: str, message: str, status_code: int):
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        status_code: int,
+        details: dict[str, Any] | None = None,
+    ):
         super().__init__(message)
         self.code = code
         self.status_code = status_code
+        # Response-body fields beyond `error.{code,message}` — e.g. verify_url,
+        # linked_wallets, claimed_operator, actual_signer, reasons. Consumers
+        # branch on these for granular recovery (see the mcp denial-code rendering
+        # in the node sibling for the canonical use). Defaults to {} so callers
+        # constructing this error by hand without a body can omit it.
+        self.details: dict[str, Any] = details or {}
 
     @property
     def status(self) -> int:

tests/test_client.py

@@ -801,6 +801,57 @@ def test_create_session_raises_on_error():
     assert exc_info.value.code == "bad_request"
 
 
+@respx.mock
+def test_create_session_forwards_address_and_operator_token():
+    """Pre-association lets a session refresh KYC for an existing identity."""
+    route = respx.post(f"{BASE_URL}/v1/sessions").mock(return_value=httpx.Response(200, json=SESSION_CREATE_PAYLOAD))
+    client = AgentScore(api_key=API_KEY)
+    client.create_session(address="0xabc", operator_token="opc_xyz")
+    body = json.loads(route.calls.last.request.content)
+    assert body["address"] == "0xabc"
+    assert body["operator_token"] == "opc_xyz"
+
+
+@respx.mock
+def test_error_response_populates_details_with_non_error_fields():
+    """Non-`error` response-body keys flow into AgentScoreError.details so consumers
+    can branch on verify_url, linked_wallets, claimed_operator, etc. for granular recovery."""
+    respx.post(f"{BASE_URL}/v1/assess").mock(
+        return_value=httpx.Response(
+            403,
+            json={
+                "error": {"code": "wallet_signer_mismatch", "message": "Signer mismatch"},
+                "claimed_operator": "op_abc",
+                "actual_signer": "0xdef",
+                "linked_wallets": ["0xabc", "0xdef"],
+            },
+        )
+    )
+    client = AgentScore(api_key=API_KEY)
+    with pytest.raises(AgentScoreError) as exc_info:
+        client.assess(address="0xabc")
+    err = exc_info.value
+    assert err.code == "wallet_signer_mismatch"
+    assert err.details["claimed_operator"] == "op_abc"
+    assert err.details["actual_signer"] == "0xdef"
+    assert err.details["linked_wallets"] == ["0xabc", "0xdef"]
+    assert "error" not in err.details  # the `error` key is parsed into code/message, not echoed
+
+
+@respx.mock
+def test_error_response_with_no_extra_fields_yields_empty_details():
+    respx.post(f"{BASE_URL}/v1/assess").mock(
+        return_value=httpx.Response(
+            500,
+            json={"error": {"code": "internal_error", "message": "Boom"}},
+        )
+    )
+    client = AgentScore(api_key=API_KEY)
+    with pytest.raises(AgentScoreError) as exc_info:
+        client.assess(address="0xabc")
+    assert exc_info.value.details == {}
+
+
 # ---------------------------------------------------------------------------
 # poll_session
 # ---------------------------------------------------------------------------
@@ -1047,6 +1098,18 @@ async def test_acreate_session_with_first_class_fields():
     await client.aclose()
 
 
+@pytest.mark.asyncio
+@respx.mock
+async def test_acreate_session_forwards_address_and_operator_token():
+    route = respx.post(f"{BASE_URL}/v1/sessions").mock(return_value=httpx.Response(200, json=SESSION_CREATE_PAYLOAD))
+    client = AgentScore(api_key=API_KEY)
+    await client.acreate_session(address="0xabc", operator_token="opc_xyz")
+    body = json.loads(route.calls.last.request.content)
+    assert body["address"] == "0xabc"
+    assert body["operator_token"] == "opc_xyz"
+    await client.aclose()
+
+
 # ---------------------------------------------------------------------------
 # Async: apoll_session
 # ---------------------------------------------------------------------------

tests/test_errors.py

@@ -34,3 +34,23 @@ def test_unknown_error_code():
     err = AgentScoreError(code="unknown_error", message="Something went wrong", status_code=500)
     assert err.code == "unknown_error"
     assert err.status_code == 500
+
+
+def test_details_defaults_to_empty_dict_when_omitted():
+    err = AgentScoreError(code="not_found", message="Not found", status_code=404)
+    assert err.details == {}
+
+
+def test_details_preserves_response_body_fields_for_granular_recovery():
+    err = AgentScoreError(
+        code="wallet_signer_mismatch",
+        message="Signer mismatch",
+        status_code=403,
+        details={
+            "claimed_operator": "op_abc",
+            "actual_signer": "0xdef",
+            "linked_wallets": ["0xabc", "0xdef"],
+        },
+    )
+    assert err.details["claimed_operator"] == "op_abc"
+    assert err.details["linked_wallets"] == ["0xabc", "0xdef"]