counterpart 0.1.0__py3-none-any.whl

counterpart/__init__.py

@@ -0,0 +1,35 @@
+"""counterpart: test your A2A agent against simulated counterparty agents.
+
+Test your A2A agent against simulated counterparties — cooperative, broken, or
+hostile — before you connect it to a real one. The centerpiece is catching a peer
+that reports success while returning incomplete or corrupt work (silent partial
+completion), via declarative contract assertions and an adversarial persona suite.
+"""
+
+__version__ = "0.1.0"
+
+from typing import Any
+
+from counterpart.adapters.a2a.client import A2AClient, TaskResult
+from counterpart.adapters.a2a.mockagent import MockAgent
+from counterpart.adapters.a2a.wrap import wrap
+from counterpart.core.contract import Contract, ContractReport, FailureCategory
+from counterpart.personas import available as available_personas
+
+
+def mock_agent(persona: str = "cooperative", **config: Any) -> MockAgent:
+    """Convenience factory mirroring the pytest fixture: ``mock_agent(persona=...)``."""
+    return MockAgent(persona, **config)
+
+
+__all__ = [
+    "A2AClient",
+    "Contract",
+    "ContractReport",
+    "FailureCategory",
+    "MockAgent",
+    "TaskResult",
+    "available_personas",
+    "mock_agent",
+    "wrap",
+]

counterpart/adapters/__init__.py

@@ -0,0 +1 @@
+"""Protocol adapters. Each subpackage binds the protocol-agnostic core to one wire protocol."""

counterpart/adapters/a2a/__init__.py

@@ -0,0 +1,151 @@
+"""A2A protocol adapter: protocol types today; Agent Card serving, task lifecycle,
+JSON-RPC transport, and SSE streaming land in milestone 3.
+
+Targets A2A spec v1.0 (verified against release tag v1.0.1); see docs/spec-notes.md.
+"""
+
+from counterpart.adapters.a2a.constants import (
+    A2A_EXTENSIONS_HEADER,
+    A2A_VERSION_HEADER,
+    BINDING_GRPC,
+    BINDING_HTTP_JSON,
+    BINDING_JSONRPC,
+    ERROR_HTTP_STATUS,
+    ERROR_INFO_DOMAIN,
+    ERROR_INFO_TYPE_URL,
+    ERROR_NAMES,
+    JSONRPC_VERSION,
+    MEDIA_TYPE_A2A_JSON,
+    MEDIA_TYPE_JSON,
+    MEDIA_TYPE_SSE,
+    PROTOCOL_VERSION,
+    SPEC_RELEASE,
+    STANDARD_ERROR_MESSAGES,
+    WELL_KNOWN_AGENT_CARD_PATH,
+    A2AErrorCode,
+    A2AMethod,
+    error_reason,
+)
+from counterpart.adapters.a2a.types import (
+    AgentCapabilities,
+    AgentCard,
+    AgentCardSignature,
+    AgentExtension,
+    AgentInterface,
+    AgentProvider,
+    AgentSkill,
+    APIKeySecurityScheme,
+    Artifact,
+    AuthenticationInfo,
+    AuthorizationCodeOAuthFlow,
+    CancelTaskRequest,
+    ClientCredentialsOAuthFlow,
+    DeleteTaskPushNotificationConfigRequest,
+    DeviceCodeOAuthFlow,
+    GetExtendedAgentCardRequest,
+    GetTaskPushNotificationConfigRequest,
+    GetTaskRequest,
+    HTTPAuthSecurityScheme,
+    ImplicitOAuthFlow,
+    JSONRPCError,
+    JSONRPCErrorResponse,
+    JSONRPCRequest,
+    JSONRPCSuccessResponse,
+    ListTaskPushNotificationConfigsRequest,
+    ListTaskPushNotificationConfigsResponse,
+    ListTasksRequest,
+    ListTasksResponse,
+    Message,
+    MutualTlsSecurityScheme,
+    OAuth2SecurityScheme,
+    OAuthFlows,
+    OpenIdConnectSecurityScheme,
+    Part,
+    PasswordOAuthFlow,
+    Role,
+    SecurityRequirement,
+    SecurityScheme,
+    SendMessageConfiguration,
+    SendMessageRequest,
+    SendMessageResponse,
+    StreamResponse,
+    SubscribeToTaskRequest,
+    Task,
+    TaskArtifactUpdateEvent,
+    TaskPushNotificationConfig,
+    TaskState,
+    TaskStatus,
+    TaskStatusUpdateEvent,
+)
+
+__all__ = [
+    "A2A_EXTENSIONS_HEADER",
+    "A2A_VERSION_HEADER",
+    "BINDING_GRPC",
+    "BINDING_HTTP_JSON",
+    "BINDING_JSONRPC",
+    "ERROR_HTTP_STATUS",
+    "ERROR_INFO_DOMAIN",
+    "ERROR_INFO_TYPE_URL",
+    "ERROR_NAMES",
+    "JSONRPC_VERSION",
+    "MEDIA_TYPE_A2A_JSON",
+    "MEDIA_TYPE_JSON",
+    "MEDIA_TYPE_SSE",
+    "PROTOCOL_VERSION",
+    "SPEC_RELEASE",
+    "STANDARD_ERROR_MESSAGES",
+    "WELL_KNOWN_AGENT_CARD_PATH",
+    "A2AErrorCode",
+    "A2AMethod",
+    "APIKeySecurityScheme",
+    "AgentCapabilities",
+    "AgentCard",
+    "AgentCardSignature",
+    "AgentExtension",
+    "AgentInterface",
+    "AgentProvider",
+    "AgentSkill",
+    "Artifact",
+    "AuthenticationInfo",
+    "AuthorizationCodeOAuthFlow",
+    "CancelTaskRequest",
+    "ClientCredentialsOAuthFlow",
+    "DeleteTaskPushNotificationConfigRequest",
+    "DeviceCodeOAuthFlow",
+    "GetExtendedAgentCardRequest",
+    "GetTaskPushNotificationConfigRequest",
+    "GetTaskRequest",
+    "HTTPAuthSecurityScheme",
+    "ImplicitOAuthFlow",
+    "JSONRPCError",
+    "JSONRPCErrorResponse",
+    "JSONRPCRequest",
+    "JSONRPCSuccessResponse",
+    "ListTaskPushNotificationConfigsRequest",
+    "ListTaskPushNotificationConfigsResponse",
+    "ListTasksRequest",
+    "ListTasksResponse",
+    "Message",
+    "MutualTlsSecurityScheme",
+    "OAuth2SecurityScheme",
+    "OAuthFlows",
+    "OpenIdConnectSecurityScheme",
+    "Part",
+    "PasswordOAuthFlow",
+    "Role",
+    "SecurityRequirement",
+    "SecurityScheme",
+    "SendMessageConfiguration",
+    "SendMessageRequest",
+    "SendMessageResponse",
+    "StreamResponse",
+    "SubscribeToTaskRequest",
+    "Task",
+    "TaskArtifactUpdateEvent",
+    "TaskPushNotificationConfig",
+    "TaskState",
+    "TaskStatus",
+    "TaskStatusUpdateEvent",
+    "error_reason",
+]

counterpart/adapters/a2a/client.py

@@ -0,0 +1,263 @@
+"""A2A client role: send a task to an A2A agent and get back a verifiable result.
+
+Talks to any A2A v1.0 JSON-RPC agent — a real one over the network (``base_url``) or an
+in-process one over ASGI (``app``, no socket, for fast/deterministic tests). Returns a
+:class:`TaskResult` that carries the peer's self-reported status next to the extracted
+result, and can verify both against a :class:`~counterpart.core.contract.Contract`.
+
+v0 routes JSON-RPC to ``{base}/`` and fetches the card from the well-known path; honouring
+the card's declared interface URL for routing is the conformance checker's job (roadmap).
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+from counterpart.adapters.a2a.constants import (
+    A2A_VERSION_HEADER,
+    MEDIA_TYPE_JSON,
+    PROTOCOL_VERSION,
+    WELL_KNOWN_AGENT_CARD_PATH,
+    A2AMethod,
+)
+from counterpart.adapters.a2a.types import (
+    AgentCard,
+    Artifact,
+    JSONRPCRequest,
+    JSONRPCSuccessResponse,
+    Message,
+    Part,
+    Role,
+    SendMessageConfiguration,
+    SendMessageRequest,
+    StreamResponse,
+    Task,
+    TaskState,
+)
+from counterpart.core.contract import Contract, ContractReport
+
+
+def _extract_result(task: Task) -> Any:
+    """The delegated result to verify: the latest artifact's data, else its text.
+
+    Prefers a structured ``data`` part over ``text`` regardless of part order (a contract's
+    ``.returns(Model)`` wants the structured payload), then falls back to text.
+    """
+    if not task.artifacts:
+        return None
+    parts = task.artifacts[-1].parts
+    for part in parts:
+        if part.data is not None:
+            return part.data
+    for part in parts:
+        if part.text is not None:
+            return part.text
+    return None
+
+
+@dataclass
+class TaskResult:
+    """The outcome of sending a task: the raw task, the states seen, and any contract report."""
+
+    task: Task
+    states: list[str] = field(default_factory=list)  # friendly aliases, in order
+    report: ContractReport[Any] | None = None
+
+    @property
+    def status(self) -> str:
+        """The peer's final self-reported status, as a friendly alias (e.g. ``"completed"``)."""
+        return self.task.status.state.alias
+
+    @property
+    def result(self) -> Any:
+        return _extract_result(self.task)
+
+    @property
+    def artifacts(self) -> list[Artifact]:
+        return self.task.artifacts or []
+
+    @property
+    def completed(self) -> bool:
+        return self.task.status.state is TaskState.COMPLETED
+
+    @property
+    def contract_violated(self) -> bool:
+        """True if a contract was supplied and the delegated result did not satisfy it."""
+        return self.report is not None and self.report.contract_violated
+
+    def reached_state(self, state: str) -> bool:
+        return TaskState.coerce(state).alias in self.states
+
+
+class A2AClient:
+    """An async A2A JSON-RPC client. Use ``base_url`` for a real agent, ``app`` for ASGI."""
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        *,
+        app: Any = None,
+        timeout: float = 30.0,
+        protocol_version: str = PROTOCOL_VERSION,
+    ) -> None:
+        if (base_url is None) == (app is None):
+            raise ValueError("provide exactly one of base_url or app")
+        self._protocol_version = protocol_version
+        if app is not None:
+            self._base = "http://mock.local"
+            transport: httpx.AsyncBaseTransport = httpx.ASGITransport(app=app)
+            self._http = httpx.AsyncClient(
+                transport=transport, base_url=self._base, timeout=timeout
+            )
+        else:
+            self._base = base_url.rstrip("/")  # type: ignore[union-attr]
+            self._http = httpx.AsyncClient(base_url=self._base, timeout=timeout)
+
+    async def __aenter__(self) -> A2AClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    def _headers(self) -> dict[str, str]:
+        return {A2A_VERSION_HEADER: self._protocol_version, "content-type": MEDIA_TYPE_JSON}
+
+    async def resolve_card(self) -> AgentCard:
+        """Fetch and validate the counterparty's Agent Card (spec section 8.2)."""
+        resp = await self._http.get(WELL_KNOWN_AGENT_CARD_PATH, headers=self._headers())
+        resp.raise_for_status()
+        return AgentCard.from_wire(resp.content)
+
+    def _build_message(
+        self, text: str, *, data: Any, task_id: str | None, context_id: str | None
+    ) -> Message:
+        parts = [Part(text=text)] if text else []
+        if data is not None:
+            parts.append(Part(data=data))
+        if not parts:
+            parts = [Part(text="")]
+        return Message(
+            message_id=f"msg-{uuid.uuid4().hex}",
+            role=Role.USER,
+            parts=parts,
+            task_id=task_id,
+            context_id=context_id,
+        )
+
+    async def send_message(
+        self,
+        text: str,
+        *,
+        data: Any = None,
+        task_id: str | None = None,
+        context_id: str | None = None,
+        stream: bool = False,
+        contract: Contract[Any] | None = None,
+    ) -> TaskResult:
+        """Send a task (or a follow-up, if ``task_id`` is set) and return the result."""
+        message = self._build_message(text, data=data, task_id=task_id, context_id=context_id)
+        request = SendMessageRequest(
+            message=message,
+            configuration=SendMessageConfiguration(accepted_output_modes=["application/json"]),
+        )
+        if stream:
+            result = await self._send_streaming(request)
+        else:
+            result = await self._send_blocking(request)
+        if contract is not None:
+            result.report = contract.verify(result=result.result, reported_status=result.status)
+        return result
+
+    async def reply(
+        self, task_id: str, text: str, *, context_id: str | None = None, **kw: Any
+    ) -> TaskResult:
+        """Continue an interrupted task (e.g. answer an input-required question, spec 3.4.3)."""
+        return await self.send_message(text, task_id=task_id, context_id=context_id, **kw)
+
+    async def _send_blocking(self, request: SendMessageRequest) -> TaskResult:
+        rpc = JSONRPCRequest(method=A2AMethod.SEND_MESSAGE.value, id=1, params=request.to_wire())
+        resp = await self._http.post("/", content=rpc.to_wire_json(), headers=self._headers())
+        resp.raise_for_status()
+        body = resp.json()
+        # JSON-RPC errors arrive over HTTP 200, so surface them instead of dropping them.
+        if isinstance(body, dict) and body.get("error") is not None:
+            err = body["error"]
+            raise A2AProtocolError(
+                f"peer returned JSON-RPC error {err.get('code')}: {err.get('message')}"
+            )
+        result = body.get("result") if isinstance(body, dict) else None
+        if not isinstance(result, dict) or "task" not in result:
+            raise A2AProtocolError(f"expected a task result, got: {result!r}")
+        task = Task.from_wire(result["task"])
+        return TaskResult(task=task, states=[task.status.state.alias])
+
+    async def _send_streaming(self, request: SendMessageRequest) -> TaskResult:
+        rpc = JSONRPCRequest(
+            method=A2AMethod.SEND_STREAMING_MESSAGE.value, id=1, params=request.to_wire()
+        )
+        task: Task | None = None
+        states: list[str] = []
+        # Accumulate artifacts by id so chunked updates (append=true) are reassembled
+        # rather than duplicated (spec 4.2.2).
+        artifacts: dict[str, Artifact] = {}
+        async with self._http.stream(
+            "POST", "/", content=rpc.to_wire_json(), headers=self._headers()
+        ) as resp:
+            resp.raise_for_status()
+            async for line in resp.aiter_lines():
+                if not line.startswith("data:"):
+                    continue
+                envelope = JSONRPCSuccessResponse.from_wire(line[len("data:") :].strip())
+                event = StreamResponse.from_wire(envelope.result)
+                if event.task is not None:
+                    task = event.task
+                    states.append(event.task.status.state.alias)
+                elif event.status_update is not None:
+                    task = _apply_status(task, event.status_update)
+                    states.append(event.status_update.status.state.alias)
+                elif event.artifact_update is not None:
+                    _accumulate_artifact(artifacts, event.artifact_update)
+        if task is None:
+            raise A2AProtocolError("stream produced no task")
+        if artifacts:
+            task = task.model_copy(update={"artifacts": list(artifacts.values())})
+        return TaskResult(task=task, states=states)
+
+
+class A2AProtocolError(Exception):
+    """The peer's response did not conform to what the A2A method promises."""
+
+
+def _apply_status(task: Task | None, event: Any) -> Task:
+    if task is None:
+        raise A2AProtocolError("status update arrived before the initial task event")
+    return task.model_copy(update={"status": event.status})
+
+
+def _accumulate_artifact(artifacts: dict[str, Artifact], event: Any) -> None:
+    """Merge a TaskArtifactUpdateEvent into the id-keyed accumulator (spec 4.2.2).
+
+    ``append=true`` extends the parts of an already-seen artifact with the same id;
+    otherwise the artifact replaces (or first establishes) that id.
+    """
+    art = event.artifact
+    if event.append and art.artifact_id in artifacts:
+        existing = artifacts[art.artifact_id]
+        artifacts[art.artifact_id] = existing.model_copy(
+            update={"parts": [*existing.parts, *art.parts]}
+        )
+    else:
+        artifacts[art.artifact_id] = art
+
+
+def collect_states(results: Sequence[TaskResult]) -> list[str]:
+    """Small helper: flatten the states seen across several results (for assertions)."""
+    return [s for r in results for s in r.states]

counterpart/adapters/a2a/constants.py

@@ -0,0 +1,151 @@
+"""A2A protocol constants, verified against spec v1.0 (tag v1.0.1).
+
+Every value here is traceable to docs/spec-notes.md, which cites the spec section it
+came from. Do not "fix" a value without re-checking the spec.
+"""
+
+from enum import IntEnum, StrEnum
+from typing import Final
+
+# --- Versioning (spec section 3.6) ---
+PROTOCOL_VERSION: Final = "1.0"  # Major.Minor only; patch numbers never go on the wire
+SPEC_RELEASE: Final = "v1.0.1"  # the spec release these constants were verified against
+
+# --- Service parameters (spec sections 3.2.6, 14.2) ---
+A2A_VERSION_HEADER: Final = "A2A-Version"  # empty/absent MUST be interpreted as 0.3
+A2A_EXTENSIONS_HEADER: Final = "A2A-Extensions"  # comma-separated extension URIs
+
+# --- Discovery (spec sections 8.2, 14.3) ---
+WELL_KNOWN_AGENT_CARD_PATH: Final = "/.well-known/agent-card.json"
+
+# --- Media types (spec sections 9.1, 14.1.1) ---
+MEDIA_TYPE_JSON: Final = "application/json"  # JSON-RPC binding
+MEDIA_TYPE_A2A_JSON: Final = "application/a2a+json"  # HTTP+JSON/REST binding
+MEDIA_TYPE_SSE: Final = "text/event-stream"  # streaming responses
+
+# --- Protocol bindings (spec section 4.4.6: AgentInterface.protocolBinding) ---
+BINDING_JSONRPC: Final = "JSONRPC"
+BINDING_GRPC: Final = "GRPC"
+BINDING_HTTP_JSON: Final = "HTTP+JSON"
+
+JSONRPC_VERSION: Final = "2.0"
+
+
+class A2AMethod(StrEnum):
+    """The complete v1.0 method set (spec section 5.3 Method Mapping Reference).
+
+    These exact PascalCase strings are the JSON-RPC ``method`` values and the gRPC rpc
+    names (spec section 9.1). The v0.3 slash-style names (``message/send``, ...) do not
+    exist in v1.0.
+    """
+
+    SEND_MESSAGE = "SendMessage"
+    SEND_STREAMING_MESSAGE = "SendStreamingMessage"
+    GET_TASK = "GetTask"
+    LIST_TASKS = "ListTasks"
+    CANCEL_TASK = "CancelTask"
+    SUBSCRIBE_TO_TASK = "SubscribeToTask"
+    CREATE_TASK_PUSH_NOTIFICATION_CONFIG = "CreateTaskPushNotificationConfig"
+    GET_TASK_PUSH_NOTIFICATION_CONFIG = "GetTaskPushNotificationConfig"
+    LIST_TASK_PUSH_NOTIFICATION_CONFIGS = "ListTaskPushNotificationConfigs"
+    DELETE_TASK_PUSH_NOTIFICATION_CONFIG = "DeleteTaskPushNotificationConfig"
+    GET_EXTENDED_AGENT_CARD = "GetExtendedAgentCard"
+
+
+class A2AErrorCode(IntEnum):
+    """JSON-RPC error codes: standard (spec section 9.5) + A2A-specific (section 5.4).
+
+    A2A-specific errors use the range -32001..-32099; only -32001..-32009 are assigned
+    and -32000 is not defined in v1.0.
+    """
+
+    # Standard JSON-RPC 2.0 (spec section 9.5)
+    JSON_PARSE_ERROR = -32700
+    INVALID_REQUEST = -32600
+    METHOD_NOT_FOUND = -32601
+    INVALID_PARAMS = -32602
+    INTERNAL_ERROR = -32603
+    # A2A-specific (spec section 5.4)
+    TASK_NOT_FOUND = -32001
+    TASK_NOT_CANCELABLE = -32002
+    PUSH_NOTIFICATION_NOT_SUPPORTED = -32003
+    UNSUPPORTED_OPERATION = -32004
+    CONTENT_TYPE_NOT_SUPPORTED = -32005
+    INVALID_AGENT_RESPONSE = -32006
+    EXTENDED_AGENT_CARD_NOT_CONFIGURED = -32007
+    EXTENSION_SUPPORT_REQUIRED = -32008
+    VERSION_NOT_SUPPORTED = -32009
+
+
+# Error type names exactly as the spec tables write them (sections 5.4, 9.5).
+ERROR_NAMES: Final[dict[A2AErrorCode, str]] = {
+    A2AErrorCode.JSON_PARSE_ERROR: "JSONParseError",
+    A2AErrorCode.INVALID_REQUEST: "InvalidRequestError",
+    A2AErrorCode.METHOD_NOT_FOUND: "MethodNotFoundError",
+    A2AErrorCode.INVALID_PARAMS: "InvalidParamsError",
+    A2AErrorCode.INTERNAL_ERROR: "InternalError",
+    A2AErrorCode.TASK_NOT_FOUND: "TaskNotFoundError",
+    A2AErrorCode.TASK_NOT_CANCELABLE: "TaskNotCancelableError",
+    A2AErrorCode.PUSH_NOTIFICATION_NOT_SUPPORTED: "PushNotificationNotSupportedError",
+    A2AErrorCode.UNSUPPORTED_OPERATION: "UnsupportedOperationError",
+    A2AErrorCode.CONTENT_TYPE_NOT_SUPPORTED: "ContentTypeNotSupportedError",
+    A2AErrorCode.INVALID_AGENT_RESPONSE: "InvalidAgentResponseError",
+    A2AErrorCode.EXTENDED_AGENT_CARD_NOT_CONFIGURED: "ExtendedAgentCardNotConfiguredError",
+    A2AErrorCode.EXTENSION_SUPPORT_REQUIRED: "ExtensionSupportRequiredError",
+    A2AErrorCode.VERSION_NOT_SUPPORTED: "VersionNotSupportedError",
+}
+
+# Normative default messages exist ONLY for the five standard JSON-RPC codes
+# (spec section 9.5 table, "Standard Message" column). A2A-specific errors have no
+# normative message strings: match on code, never on message text.
+STANDARD_ERROR_MESSAGES: Final[dict[A2AErrorCode, str]] = {
+    A2AErrorCode.JSON_PARSE_ERROR: "Invalid JSON payload",
+    A2AErrorCode.INVALID_REQUEST: "Request payload validation error",
+    A2AErrorCode.METHOD_NOT_FOUND: "Method not found",
+    A2AErrorCode.INVALID_PARAMS: "Invalid parameters",
+    A2AErrorCode.INTERNAL_ERROR: "Internal error",
+}
+
+# HTTP status the same error maps to in the HTTP+JSON binding (spec section 5.4).
+# Useful to the conformance checker; the JSON-RPC binding itself replies HTTP 200.
+ERROR_HTTP_STATUS: Final[dict[A2AErrorCode, int]] = {
+    A2AErrorCode.JSON_PARSE_ERROR: 400,
+    A2AErrorCode.INVALID_REQUEST: 400,
+    A2AErrorCode.METHOD_NOT_FOUND: 404,
+    A2AErrorCode.INVALID_PARAMS: 400,
+    A2AErrorCode.INTERNAL_ERROR: 500,
+    A2AErrorCode.TASK_NOT_FOUND: 404,
+    A2AErrorCode.TASK_NOT_CANCELABLE: 400,
+    A2AErrorCode.PUSH_NOTIFICATION_NOT_SUPPORTED: 400,
+    A2AErrorCode.UNSUPPORTED_OPERATION: 400,
+    A2AErrorCode.CONTENT_TYPE_NOT_SUPPORTED: 400,
+    A2AErrorCode.INVALID_AGENT_RESPONSE: 500,
+    A2AErrorCode.EXTENDED_AGENT_CARD_NOT_CONFIGURED: 400,
+    A2AErrorCode.EXTENSION_SUPPORT_REQUIRED: 400,
+    A2AErrorCode.VERSION_NOT_SUPPORTED: 400,
+}
+
+
+def error_reason(code: A2AErrorCode) -> str:
+    """``google.rpc.ErrorInfo.reason`` for an A2A error (spec sections 10.6, 11.6).
+
+    The error type name in UPPER_SNAKE_CASE without the ``Error`` suffix, e.g.
+    ``TaskNotFoundError`` -> ``TASK_NOT_FOUND``. The spec states this rule for the
+    A2A-specific errors; we apply the same derivation to the standard JSON-RPC names
+    (e.g. ``InternalError`` -> ``INTERNAL``). ``domain`` is always ``a2a-protocol.org``.
+    """
+    name = ERROR_NAMES[code].removesuffix("Error")
+    # CamelCase -> UPPER_SNAKE, keeping acronym runs together ("JSONParse" -> "JSON_PARSE").
+    out: list[str] = []
+    for i, ch in enumerate(name):
+        starts_word = ch.isupper() and i > 0
+        after_lower = i > 0 and not name[i - 1].isupper()
+        before_lower = i + 1 < len(name) and name[i + 1].islower()
+        if starts_word and (after_lower or before_lower):
+            out.append("_")
+        out.append(ch)
+    return "".join(out).upper()
+
+
+ERROR_INFO_DOMAIN: Final = "a2a-protocol.org"
+ERROR_INFO_TYPE_URL: Final = "type.googleapis.com/google.rpc.ErrorInfo"