feat(server): response_enhancer callback (JS #2161 parity) (#933)

* feat(server): add response_enhancer callback (JS #2161 parity)

Add a server-wide response_enhancer callback that stamps cross-cutting
fields on every response class — framework-tool successes, custom-tool
successes (get_task_status / list_tasks), the pre-auth
get_adcp_capabilities discovery response, and structured adcp_error
responses — uniformly across the MCP and A2A transports.

The Python SDK has no single response finalizer, so the enhancer is wired
at the three dispatch seams that converge the response classes, all AFTER
inject_context (so a buggy enhancer cannot re-introduce a stripped
credential into the echo envelope):

1. Success — create_tool_caller (mcp_tools.py): after inject_context and
   before validate_response, so a conformance-breaking mutation surfaces
   as VALIDATION_ERROR rather than shipping malformed. Covers framework
   tools, custom tools, and get_adcp_capabilities on both transports.
2. MCP errors — build_mcp_error_result (translate.py).
3. A2A errors — _send_adcp_error (a2a_server.py).

Also closes the A2A comply_test_controller gap: that skill bypasses
create_tool_caller via _call_test_controller, so the enhancer is applied
there too (context echoed first to preserve the credential-echo invariant).

The enhancer supports both a context-blind Callable[[dict], None] and a
context-aware Callable[[str, dict, ToolContext | None], None], dispatched
by signature arity. It runs synchronously, mutates in place, and a raised
exception is caught + logged at WARNING — a buggy enhancer must not become
a transport error.

response_enhancer threads through ServeConfig, serve(), all three
_serve_* transport paths, create_mcp_server / create_a2a_server, and the
in-process build_asgi_app / build_test_client test harness.
adcp.decisioning.serve.serve forwards it via **serve_kwargs. The
ResponseEnhancer type alias is exported from adcp.server (matching
ServeConfig / SkillMiddleware; adcp.__all__ snapshot unchanged).

Idempotency note: the cache commits the pre-enhancement response, so a
replay re-runs the enhancer — non-idempotent enhancers diverge on replay.

Closes #926

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

* docs(server): document response_enhancer coverage seams

The ResponseEnhancer / serve() docstrings claimed the enhancer applies to
"every response". Two paths are not enhanced:

- the MCP comply_test_controller sandbox path returns the handler result
  directly without a success-path enhancer call (its A2A counterpart is
  stamped);
- a handler that returns (vs raises) a raw L3 {"adcp_error": {...}}
  envelope is skipped by the success-path guard and never reaches the
  raised-error finalizers.

Document the exact enhanced paths and these two gaps on the canonical
ResponseEnhancer docstring, point _apply_response_enhancer at it, and
soften the serve() docstrings from "every response". Docstring-only; no
behavior change.

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

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: bokelley

src/adcp/decisioning/serve.py

@@ -527,6 +527,9 @@ def serve(
     :param serve_kwargs: Forwarded to :func:`adcp.server.serve`. Use
         for ``host``, ``port``, ``transport``, ``test_controller``,
         ``context_factory``, ``middleware``, ``validation``,
+        ``response_enhancer`` (a server-wide
+        :data:`~adcp.server.ResponseEnhancer` applied to every response
+        on both transports),
         ``config`` (:class:`adcp.server.ServeConfig` bundle), etc.
         Pass ``config=ServeConfig(transport="a2a", ...)`` to supply
         all server options as a single typed object rather than

src/adcp/server/__init__.py

@@ -99,6 +99,7 @@ async def get_products(params, context=None):
     TERMINAL_CODES,
     TRANSIENT_CODES,
     AccountError,
+    ResponseEnhancer,
     adcp_error,
     cancel_media_buy_response,
     inject_context,
@@ -212,6 +213,7 @@ async def get_products(params, context=None):
     "MCPToolSet",
     "MCPSessionStats",
     "RequestMetadata",
+    "ResponseEnhancer",
     "ServeConfig",
     "create_mcp_tools",
     "create_mcp_server",

src/adcp/server/a2a_server.py

@@ -37,6 +37,7 @@
 
 from adcp.exceptions import ADCPError
 from adcp.server.base import ADCPHandler, ToolContext
+from adcp.server.helpers import ResponseEnhancer, _apply_response_enhancer
 from adcp.server.spec_compat import PreValidationHooks
 
 # Decisioning-layer ``AdcpError`` (from ``adcp.decisioning.types``) is the
@@ -200,10 +201,12 @@ def __init__(
         validation: ValidationHookConfig | None = SERVER_DEFAULT_VALIDATION,
         pre_validation_hooks: PreValidationHooks | None = None,
         test_controller_account_resolver: Any | None = None,
+        response_enhancer: ResponseEnhancer | None = None,
     ) -> None:
         self._handler = handler
         self._context_factory = context_factory
         self._test_controller_account_resolver = test_controller_account_resolver
+        self._response_enhancer = response_enhancer
         # Store as a tuple so the executor can't be mutated from underneath
         # at runtime (a flaky test or a handler reaching self._middleware
         # can't corrupt the dispatch chain). Tuple ordering = runtime
@@ -232,6 +235,7 @@ def __init__(
                 validation=validation,
                 pre_validation_hook=hook,
                 default_unnegotiated_adcp_version=None,
+                response_enhancer=response_enhancer,
             )
 
         if test_controller is not None:
@@ -253,16 +257,33 @@ def _register_test_controller(self, store: TestControllerStore) -> None:
         """
 
         resolver = self._test_controller_account_resolver
+        response_enhancer = self._response_enhancer
 
         async def _call_test_controller(
             params: dict[str, Any], context: ToolContext | None = None
         ) -> Any:
-            return await _handle_test_controller(
+            result = await _handle_test_controller(
                 store,
                 params,
                 context=context,
                 account_resolver=resolver,
             )
+            # This skill bypasses ``create_tool_caller`` (the success-path
+            # enhancer site), so apply the enhancer here too — otherwise
+            # comply responses would silently skip the seller's
+            # cross-cutting stamp. Echo context first so the enhancer runs
+            # after the credential-stripped envelope is assembled (the
+            # later ``_send_result`` ``inject_context`` then no-ops),
+            # preserving the credential-echo invariant the other sites
+            # uphold.
+            if isinstance(result, dict):
+                from adcp.server.helpers import inject_context
+
+                inject_context(params, result)
+                _apply_response_enhancer(
+                    response_enhancer, "comply_test_controller", result, context
+                )
+            return result
 
         self._tool_callers["comply_test_controller"] = _call_test_controller
 
@@ -303,7 +324,9 @@ async def execute(self, context: RequestContext, event_queue: EventQueue) -> Non
             # channel is reserved for transport-level errors (auth
             # rejected, rate-limited pre-dispatch).
             logger.info("AdCP application error for skill %s: %s", skill_name, exc)
-            await self._send_adcp_error(event_queue, context, exc, params)
+            await self._send_adcp_error(
+                event_queue, context, exc, params, skill_name=skill_name, tool_context=tool_context
+            )
         except Exception:
             logger.exception("Error executing skill %s", skill_name)
             await self._send_error(event_queue, context, f"Skill execution failed: {skill_name}")
@@ -512,6 +535,9 @@ async def _send_adcp_error(
         context: RequestContext,
         exc: Any,
         params: dict[str, Any] | None = None,
+        *,
+        skill_name: str = "",
+        tool_context: ToolContext | None = None,
     ) -> None:
         """Publish a failed task carrying an AdCP ``adcp_error`` payload.
 
@@ -564,6 +590,13 @@ async def _send_adcp_error(
         if params is not None:
             inject_context(params, data)
 
+        # Run the seller's response enhancer on the error envelope AFTER
+        # the context echo (so a stripped credential can't be
+        # re-introduced) — symmetric with the MCP error path
+        # (``build_mcp_error_result``) and the success path. A buggy
+        # enhancer is caught and logged inside the helper.
+        _apply_response_enhancer(self._response_enhancer, skill_name, data, tool_context)
+
         task = _make_task(
             context,
             state=pb.TaskState.TASK_STATE_FAILED,
@@ -819,15 +852,13 @@ def _validate_card_url(url: str) -> str:
     parsed = urlparse(url)
     if not parsed.scheme or not parsed.netloc:
         raise ValueError(
-            f"public_url resolver returned {url!r} — "
-            "must be an absolute URL with scheme and host."
+            f"public_url resolver returned {url!r} — must be an absolute URL with scheme and host."
         )
     hostname = parsed.hostname or ""
     is_loopback = hostname in ("localhost", "127.0.0.1", "::1") or hostname.endswith(".localhost")
     if parsed.scheme != "https" and not is_loopback:
         raise ValueError(
-            f"public_url resolver returned {url!r} — "
-            "scheme must be 'https' for non-loopback hosts."
+            f"public_url resolver returned {url!r} — scheme must be 'https' for non-loopback hosts."
         )
     return url
 
@@ -941,6 +972,7 @@ def create_a2a_server(
     context_builder: Any | None = None,
     auth: BearerTokenAuth | None = None,
     public_url: str | PublicUrlResolver | None = None,
+    response_enhancer: ResponseEnhancer | None = None,
 ) -> Any:
     """Create an A2A Starlette application from an ADCP handler.
 
@@ -1067,6 +1099,15 @@ def agent_card_url(request: Request) -> str:
 
             The ``PUBLIC_URL`` env-var fallback applies only when
             ``public_url`` is ``None``; a callable takes priority.
+        response_enhancer: Optional server-wide
+            :data:`~adcp.server.ResponseEnhancer` applied to every
+            response — successes, ``adcp_error`` envelopes, and the
+            ``comply_test_controller`` skill — after the context echo and
+            (for successes) before schema validation. Mirrors the MCP-side
+            ``create_mcp_server(response_enhancer=...)`` so a single
+            callback stamps both transports. See
+            :data:`~adcp.server.ResponseEnhancer` for the supported arities
+            and failure semantics.
 
     Returns:
         A Starlette app ready to be run with uvicorn.
@@ -1088,6 +1129,7 @@ def agent_card_url(request: Request) -> str:
         validation=validation,
         pre_validation_hooks=pre_validation_hooks,
         test_controller_account_resolver=test_controller_account_resolver,
+        response_enhancer=response_enhancer,
     )
 
     if task_store is None:

src/adcp/server/helpers.py

@@ -13,12 +13,16 @@
 
 from __future__ import annotations
 
+import inspect
+import logging
 import warnings
 from collections.abc import Awaitable, Callable
 from datetime import datetime, timezone
-from typing import Any
+from typing import Any, cast
 
-from adcp.server.base import AccountAwareToolContext
+from adcp.server.base import AccountAwareToolContext, ToolContext
+
+logger = logging.getLogger("adcp.server")
 
 # All 32 codes from the ADCP spec (enums/error-code.json) plus SDK extensions.
 # Recovery classification: transient (retry), correctable (fix request), terminal.
@@ -380,6 +384,138 @@ def inject_context(
     return response
 
 
+# ============================================================================
+# Response Enhancer
+# ============================================================================
+
+ResponseEnhancer = (
+    Callable[[dict[str, Any]], None] | Callable[[str, dict[str, Any], "ToolContext | None"], None]
+)
+"""Server-wide callback that stamps cross-cutting fields on responses.
+
+Configure it via ``serve(response_enhancer=...)`` (or the matching
+:class:`~adcp.server.ServeConfig` field). The framework calls it after the
+context-echo envelope is assembled and before schema validation.
+
+Coverage — paths the enhancer runs on, both MCP and A2A unless noted:
+
+- framework-tool successes;
+- custom-tool successes (``get_task_status`` / ``list_tasks``);
+- the pre-auth ``get_adcp_capabilities`` discovery response;
+- error responses produced by a *raised* ``AdcpError`` /
+  ``ADCPTaskError`` (including credential-policy errors), which the
+  transport error finalizers stamp. The common ``adcp_error()`` helper
+  shape (``{"errors": [...]}``) carries no top-level ``adcp_error`` key,
+  so a handler that returns it is stamped on the success path;
+- the A2A ``comply_test_controller`` sandbox skill.
+
+Coverage gaps — paths the enhancer does NOT run on:
+
+- the **MCP** ``comply_test_controller`` sandbox path
+  (``test_controller.py``); it returns the handler result directly
+  without a success-path enhancer call, so its A2A counterpart is
+  stamped but its MCP counterpart is not. Sandbox-only.
+- a handler that *returns* (rather than raises) a raw AdCP L3 envelope
+  ``{"adcp_error": {...}}``. The success-path guard
+  (``if "adcp_error" not in result``) skips it, and a returned envelope
+  never reaches the raised-error finalizers, so it ships un-enhanced.
+  Raise the error (or return the ``{"errors": [...]}`` helper shape) to
+  have it stamped.
+
+Two arities are supported, dispatched by positional-parameter count:
+
+- **Context-blind** ``(result_dict) -> None`` — the common case; mutate the
+  response dict in place to stamp a field on each response it runs on.
+- **Context-aware** ``(method_name, result_dict, context) -> None`` — when
+  the stamp depends on the tool or the caller. ``context`` is the
+  :class:`~adcp.server.ToolContext` for this dispatch, or ``None`` for an
+  unauthenticated / pre-auth discovery call.
+
+The enhancer mutates the response dict in place; its return value is
+ignored. It runs **synchronously** (it is not awaited). A raised exception
+is caught and logged at ``WARNING`` — the un-enhanced response ships rather
+than turning a buggy enhancer into a transport error.
+
+Because the enhancer runs *after* the wire response is stripped of any
+credential the buyer echoed in ``context``, it cannot re-introduce a
+credential into the response envelope.
+
+Idempotency note: the server-side idempotency cache commits the
+*pre-enhancement* response, so a replayed request re-runs the enhancer.
+Non-idempotent enhancers (timestamps, random IDs) will therefore diverge
+between the original response and its replays.
+"""
+
+
+def _enhancer_is_context_aware(enhancer: ResponseEnhancer) -> bool:
+    """Return ``True`` when *enhancer* takes the 3-arg context-aware shape.
+
+    Dispatch is by positional-parameter arity: a single positional
+    parameter is the context-blind ``(result_dict)`` shape; three is the
+    context-aware ``(method_name, result_dict, context)`` shape. A callable
+    with ``*args`` is treated as context-aware so adopters writing a
+    catch-all signature still receive the method name and context.
+
+    Signature introspection failures (C callables, exotic wrappers) fall
+    back to the context-blind shape — the safe default that matches the
+    most common adopter intent.
+    """
+    try:
+        sig = inspect.signature(enhancer)
+    except (TypeError, ValueError):
+        return False
+    positional = [
+        p for p in sig.parameters.values() if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)
+    ]
+    has_var_positional = any(p.kind is p.VAR_POSITIONAL for p in sig.parameters.values())
+    return len(positional) >= 3 or has_var_positional
+
+
+def _apply_response_enhancer(
+    enhancer: ResponseEnhancer | None,
+    method_name: str,
+    result: dict[str, Any],
+    context: ToolContext | None,
+) -> dict[str, Any]:
+    """Run the configured *enhancer* against *result*, mutating it in place.
+
+    Returns the same ``result`` dict reference (no clone) so callers can use
+    the return value or the original interchangeably. When *enhancer* is
+    ``None`` the dict is returned unchanged.
+
+    The enhancer is invoked synchronously. Its return value is ignored — it
+    must mutate ``result`` in place. A raised exception is caught and logged
+    at ``WARNING`` (including *method_name*); the original ``result`` is
+    returned un-enhanced so a buggy enhancer never becomes a transport
+    error.
+
+    This is the per-call shim; whether a given dispatch path reaches it is
+    decided by the call sites. See :data:`ResponseEnhancer` for the
+    authoritative list of enhanced paths and the two coverage gaps (the MCP
+    ``comply_test_controller`` sandbox path and handler-returned raw L3
+    ``{"adcp_error": {...}}`` envelopes).
+    """
+    if enhancer is None:
+        return result
+    try:
+        if _enhancer_is_context_aware(enhancer):
+            context_aware = cast(
+                "Callable[[str, dict[str, Any], ToolContext | None], None]", enhancer
+            )
+            context_aware(method_name, result, context)
+        else:
+            context_blind = cast("Callable[[dict[str, Any]], None]", enhancer)
+            context_blind(result)
+    except Exception:
+        logger.warning(
+            "response_enhancer raised for %s — shipping the un-enhanced "
+            "response. This is a bug in the enhancer, not in the response.",
+            method_name,
+            exc_info=True,
+        )
+    return result
+
+
 # ============================================================================
 # Cancellation Helper
 # ============================================================================