fix(server): protocol-polish follow-ups from PR #341 review

ad-tech-protocol-expert called out three follow-ups from PR #341.
This PR ships #2 + #3 with concrete fixes; #1 (MCP structuredContent
migration) is documented as known-bridge — needs lowlevel
Server.call_tool refactor.

#3 — Truncation marker buyer-parseability. Pre-fix the MCP
ToolError text-suffix path emitted bare '...' as the truncation
marker, making buyer json.loads throw JSONDecodeError with no
signal of why. Now emits a sentinel object: {_truncated: true,
_reason: 'size' | 'non_serializable', _partial: '...'} — ALWAYS
valid JSON. Buyers split on '\nDetails: ' prefix, json.loads the
tail, and branch on the marker. Iterative fit replaces naive
head-room subtract so quote/backslash escaping in _partial doesn't
blow past the cap.

#2 — caused_by.type Python-only debug breadcrumb. Documented in
_internal_error_details that this field is a debug hint for the
seller dev reading their own server logs, NOT a cross-language
contract. JS sellers won't emit Python-typed exception names. Buyers
wanting structured retry/fix/abandon semantics should read
'recovery' (terminal/correctable/transient), which IS the spec
contract.

#1 — MCP structuredContent migration. Documented as bridge in
_to_mcp's docstring with the file:line citation of FastMCP's
lossy _make_error_result. The protocol-correct fix needs lowlevel
Server.call_tool registration so we can return CallToolResult
directly with structuredContent=adcp_error + isError=True;
deferred to a separate effort because it touches the FastMCP→
lowlevel boundary throughout serve.py.

Tests: 1 updated (truncation now asserts parseable sentinel),
1 new (unserializable details emits sentinel, not malformed JSON).
Test count: 2883 (was 2882).

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

Author: bokelley

src/adcp/decisioning/dispatch.py

@@ -364,6 +364,20 @@ def _internal_error_details(exc: BaseException) -> dict[str, Any]:
     (typo-shaped) from ``KeyError`` (missing-config-shaped) from
     ``ConnectionError`` (network-shaped) at a glance.
 
+    **``caused_by.type`` is a debug breadcrumb, not a wire contract.**
+    The value is Python's exception class name verbatim
+    (``"AttributeError"``, ``"KeyError"``, ``"ValidationError"``).
+    Buyers built against the JS SDK won't see Python-flavoured class
+    names from JS sellers — only Python sellers leak Python types.
+    Treat this field as "hint to the seller dev reading their own
+    server logs," NOT as something to branch on programmatically
+    cross-language. The AdCP spec at ``schemas/cache/core/error.json``
+    keeps ``details`` as ``additionalProperties: true`` so this is
+    spec-compliant; it's just not portable. Buyer agents that want
+    structured retry/fix/abandon classification should read
+    ``recovery`` (terminal/correctable/transient) which IS the
+    cross-language contract.
+
     Truncation is defense-in-depth against an adopter who throws on
     secret material and ends up with a repr that includes the secret
     value verbatim. The full traceback is in the server log via

src/adcp/server/translate.py

@@ -234,11 +234,23 @@ def _to_mcp(
 
     When ``details`` is non-empty, the JSON-serialised payload is
     appended after a ``\\nDetails: `` line. Buyer agents can split on
-    that prefix and ``json.loads`` the rest. AudioStack Emma P0:
-    pre-fix the wire said "see details for cause" but the dispatch's
+    that prefix and ``json.loads`` the rest — the result is ALWAYS
+    valid JSON (truncation/serialization failures emit a sentinel
+    object, never a bare ``...``). AudioStack Emma P0: pre-fix the
+    wire said "see details for cause" but the dispatch's
     ``details.caused_by`` (and #341's ``validation_errors``) never
     reached MCP buyers — only A2A. Now both transports surface the
     structured breadcrumb.
+
+    **Bridge, not endpoint.** The protocol-correct shape is MCP's
+    ``CallToolResult.structuredContent`` (carries ``isError=True``
+    AND a structured ``adcp_error`` object on the same envelope —
+    see ``mcp.types.CallToolResult``). FastMCP's
+    ``_make_error_result`` (``mcp/server/lowlevel/server.py:467``)
+    drops ``structuredContent`` for error results, so we can't reach
+    that channel via FastMCP's ``ToolError`` raise path. Migrating
+    to lowlevel ``Server.call_tool`` registration would unlock it;
+    until then this text-suffix is the working bridge.
     """
     if field:
         text = f"{code}[{field}]: {message}"
@@ -247,20 +259,86 @@ def _to_mcp(
     if suggestion:
         text += f"\nSuggestion: {suggestion}"
     if details:
-        # Truncation: the entire MCP error is one ``text`` field, so a
-        # huge details dict bloats every error response. Cap the JSON
-        # payload at 8 KB — generous enough for the structured
-        # breadcrumb shapes (caused_by + validation_errors typically
-        # under 2 KB) but bounded against an adopter who fills details
-        # with raw repr or DB query strings.
+        text += f"\nDetails: {_serialize_details_for_mcp(details)}"
+    return ToolError(text)
+
+
+#: Cap on the JSON-serialised ``details`` payload appended to MCP
+#: ToolError text. Generous enough for typical
+#: ``caused_by`` + ``validation_errors`` shapes (under 2 KB) and
+#: bounded against an adopter who fills ``details`` with raw repr
+#: or DB query strings. Not configurable today; if an adopter
+#: needs more, an env-var escape hatch is the right next step.
+_MCP_DETAILS_MAX_BYTES = 8192
+
+
+def _serialize_details_for_mcp(details: dict[str, Any]) -> str:
+    """Serialise ``details`` to a JSON string suitable for embedding
+    in the MCP ToolError text payload.
+
+    The output is ALWAYS valid JSON — even when truncation fires
+    or ``json.dumps`` raises. Buyer agents can split on the
+    ``\\nDetails: `` prefix and ``json.loads`` the tail without
+    branching on serialization quality. Truncation is signalled via
+    the ``_truncated`` field on the sentinel object so buyers can
+    surface a "details elided; see server logs" UX hint.
+
+    Pre-fix (PR #341 ship): truncation emitted a bare ``...`` suffix
+    on the JSON tail, which made the buyer's ``json.loads`` throw
+    ``JSONDecodeError`` with no signal that the cause was
+    server-side truncation. ad-tech-protocol-expert called this
+    out as a follow-up before the wire shape became de-facto
+    convention.
+    """
+    try:
+        details_json = json.dumps(details, separators=(",", ":"), default=str)
+    except Exception:
+        # Non-serializable details (rare — ``default=str`` catches
+        # most). Emit a sentinel so the buyer's parse still
+        # succeeds. ``str(details)`` may also raise on circular refs
+        # — guarded with try/except + a fallback empty partial.
         try:
-            details_json = json.dumps(details, separators=(",", ":"), default=str)
+            partial = str(details)[: _MCP_DETAILS_MAX_BYTES // 2]
         except Exception:
-            details_json = str(details)
-        if len(details_json) > 8192:
-            details_json = details_json[:8189] + "..."
-        text += f"\nDetails: {details_json}"
-    return ToolError(text)
+            partial = ""
+        return json.dumps(
+            {
+                "_truncated": True,
+                "_reason": "non_serializable",
+                "_partial": partial,
+            },
+            separators=(",", ":"),
+        )
+    if len(details_json) <= _MCP_DETAILS_MAX_BYTES:
+        return details_json
+    # Truncation: emit a sentinel object (always valid JSON).
+    # ``_partial`` carries as much of the original payload as fits
+    # inside the cap; buyers that want the full payload pull it
+    # from server logs (still in ``logger.exception`` traces).
+    #
+    # Iterate to fit: JSON encoding of ``_partial`` adds backslash
+    # escaping (each `"` becomes `\\"`, each `\\` becomes `\\\\`),
+    # so a naive headroom calc undershoots when the partial contains
+    # quotes or backslashes. Halve until the encoded sentinel fits.
+    cut = _MCP_DETAILS_MAX_BYTES - 64  # rough headroom for sentinel keys
+    while cut > 0:
+        encoded = json.dumps(
+            {
+                "_truncated": True,
+                "_reason": "size",
+                "_partial": details_json[:cut],
+            },
+            separators=(",", ":"),
+        )
+        if len(encoded) <= _MCP_DETAILS_MAX_BYTES:
+            return encoded
+        cut = max(0, cut - max(64, (len(encoded) - _MCP_DETAILS_MAX_BYTES) * 2))
+    # Cut hit zero — emit a no-partial sentinel so the buyer still
+    # sees that something was truncated.
+    return json.dumps(
+        {"_truncated": True, "_reason": "size", "_partial": ""},
+        separators=(",", ":"),
+    )
 
 
 def _to_a2a(

tests/test_translate.py

@@ -458,15 +458,21 @@ def test_validation_errors_reach_mcp_buyer_via_details(self) -> None:
         loc_fields = {err["loc"][-1] for err in parsed["validation_errors"]}
         assert loc_fields == {"width", "height"}
 
-    def test_huge_details_truncated_at_8kb(self) -> None:
+    def test_huge_details_truncated_with_parseable_sentinel(self) -> None:
         """A pathological ``details`` payload (huge repr, DB query
-        string) gets truncated to 8KB so the MCP error response stays
-        bounded. Defense-in-depth against an adopter who fills
-        ``details`` with raw debug payloads."""
+        string) gets truncated to 8 KB so the MCP error response
+        stays bounded. The truncated payload is ALWAYS valid JSON —
+        emits a ``{"_truncated": true, "_reason": "size", "_partial":
+        "..."}`` sentinel so buyer agents can ``json.loads`` and
+        branch on the marker (ad-tech-protocol-expert P1 follow-up
+        from PR #341 — pre-fix the bare ``...`` suffix made buyer
+        ``json.loads`` throw ``JSONDecodeError`` with no signal of
+        why)."""
+        import json as _json
+
         from adcp.decisioning.types import AdcpError as DecisioningAdcpError
         from adcp.server.translate import translate_error
 
-        # Build a details dict that JSON-encodes to >8 KB.
         big = {"blob": "X" * 10_000}
         exc = DecisioningAdcpError(
             "INTERNAL_ERROR",
@@ -478,4 +484,37 @@ def test_huge_details_truncated_at_8kb(self) -> None:
         text = str(tool_err.args[0]) if tool_err.args else str(tool_err)
         details_part = text.split("\nDetails: ", 1)[1]
         assert len(details_part) <= 8192
-        assert details_part.endswith("...")
+        # Critical: the truncated payload MUST be valid JSON.
+        parsed = _json.loads(details_part)
+        assert parsed["_truncated"] is True
+        assert parsed["_reason"] == "size"
+        assert "_partial" in parsed
+
+    def test_unserializable_details_emits_sentinel(self) -> None:
+        """When ``json.dumps`` itself raises (a circular reference or
+        other unrepresentable shape that even ``default=str`` can't
+        coerce), the function emits a parseable sentinel rather than
+        letting the failure propagate or returning malformed JSON."""
+        import json as _json
+
+        from adcp.decisioning.types import AdcpError as DecisioningAdcpError
+        from adcp.server.translate import translate_error
+
+        # Circular reference defeats both ``json.dumps`` and the
+        # ``default=str`` fallback (str() can't represent the cycle
+        # either — it raises ``ValueError: Circular reference``).
+        circular: dict[str, object] = {}
+        circular["self"] = circular
+        exc = DecisioningAdcpError(
+            "INTERNAL_ERROR",
+            message="circular",
+            recovery="terminal",
+            details=circular,
+        )
+        tool_err = translate_error(exc, protocol="mcp")
+        text = str(tool_err.args[0]) if tool_err.args else str(tool_err)
+        details_part = text.split("\nDetails: ", 1)[1]
+        # Even on serialization failure, the output is parseable.
+        parsed = _json.loads(details_part)
+        assert parsed["_truncated"] is True
+        assert parsed["_reason"] == "non_serializable"