agentship-core 0.0.1__py3-none-any.whl

agentship/__init__.py

@@ -0,0 +1,53 @@
+"""AgentShip — an open, recipe-first harness for agentic systems.
+
+Author an agent (or a team) in YAML or Python and get the plumbing wired behind
+small, stable seams. This module re-exports the kernel's public surface: the spec,
+the identity backbone, the runtime, and the error taxonomy.
+"""
+
+from __future__ import annotations
+
+from .context import Caller, RunContext, RunMode, get_run_context
+from .engines.base import Engine, EngineCapabilities, Event, Result, ResumeToken
+from .errors import (
+    AgentShipError,
+    CapabilityError,
+    EngineNotFoundError,
+    SpecError,
+)
+from .middleware import Middleware
+from .primitives.model_router import (
+    DefaultModelRouter,
+    ModelRouter,
+    resolve_model_router,
+)
+from .runtime import RunnableAgent, build_agent
+from .spec import AgentSpec, MemberSpec, ModelParams, ObservabilitySpec, load_spec, resolve_code
+
+__all__ = [
+    "AgentSpec",
+    "MemberSpec",
+    "ModelParams",
+    "ObservabilitySpec",
+    "load_spec",
+    "resolve_code",
+    "Caller",
+    "RunContext",
+    "RunMode",
+    "get_run_context",
+    "RunnableAgent",
+    "build_agent",
+    "Middleware",
+    "ModelRouter",
+    "DefaultModelRouter",
+    "resolve_model_router",
+    "Engine",
+    "EngineCapabilities",
+    "Event",
+    "ResumeToken",
+    "Result",
+    "AgentShipError",
+    "SpecError",
+    "CapabilityError",
+    "EngineNotFoundError",
+]

agentship/a2a/__init__.py

@@ -0,0 +1,53 @@
+"""A2A (agent-to-agent) interop — the optional networked-specialist layer (Phase 05).
+
+This package is **Layer 1**: it is imported only when an agent opts into A2A (a networked
+``specialists[].a2a:`` block or an ``a2a.expose: true`` block in YAML). Layer 0 — in-process
+specialists (P02) and direct MCP (P03) — never touches it, so the whole ``agentship.a2a``
+subtree can be absent and the default runtime stays green (the ``interop.optional`` invariant).
+
+It carries the transport-agnostic pieces that live in core: the A2A wire models
+(:mod:`agentship.a2a.models`), Agent Card generation (:mod:`agentship.a2a.card`), and the
+:class:`~agentship.a2a.resolver.SpecialistResolver` that turns one ``AgentRef`` into either an
+in-process or a networked specialist — so a supervisor's ``kit.specialist(name)`` call is
+identical whichever side of the wire the specialist lives on. The FastAPI server adapter that
+*exposes* an agent over A2A lives in ``agentship_service.a2a`` (it needs the web app), not here.
+"""
+
+from __future__ import annotations
+
+from .bridge import agent_ref_from_member
+from .card import build_agent_card
+from .client import HttpxTransport, RemoteA2aAgent
+from .models import (
+    AgentCapabilities,
+    AgentCard,
+    AgentRef,
+    AgentSkill,
+    JsonRpcRequest,
+    JsonRpcResponse,
+    Message,
+    RemoteSpec,
+    TextPart,
+)
+from .resolver import SpecialistResolver
+from .specialist import LocalSpecialist, RemoteSpecialist, Specialist
+
+__all__ = [
+    "AgentCapabilities",
+    "AgentCard",
+    "AgentRef",
+    "AgentSkill",
+    "HttpxTransport",
+    "JsonRpcRequest",
+    "JsonRpcResponse",
+    "LocalSpecialist",
+    "Message",
+    "RemoteA2aAgent",
+    "RemoteSpec",
+    "RemoteSpecialist",
+    "Specialist",
+    "SpecialistResolver",
+    "TextPart",
+    "agent_ref_from_member",
+    "build_agent_card",
+]

agentship/a2a/bridge.py

@@ -0,0 +1,44 @@
+"""Bridge the authoring layer (``MemberSpec``) to a resolvable ``AgentRef`` (§C3 connective tissue).
+
+The authoring-side blocks live in :mod:`agentship.spec` (so a spec parses with the interop layer
+absent); the resolver consumes :class:`~agentship.a2a.models.AgentRef`. This module's
+:func:`agent_ref_from_member` is the one-call translation, so a multi-agent builder treats a remote
+member and an in-process one identically — mapping each to an ``AgentRef`` and letting the resolver
+pick the transport. Kept here (a2a → spec is a one-way import) rather than in ``spec`` so the spec
+module never depends on the optional interop package.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ..errors import CapabilityError
+from .models import A2AAuthConfig, AgentRef, RemoteSpec
+
+if TYPE_CHECKING:
+    from ..spec import MemberSpec
+
+
+def agent_ref_from_member(member: MemberSpec) -> AgentRef:
+    """Map one declared team ``member`` onto the ``AgentRef`` the resolver understands.
+
+    A member with an ``a2a`` block becomes a **remote** ref (its URL/auth/timeout carried across); a
+    referenced (``ref``) or inline (``prompt``) member becomes a **local** ref keyed by the member
+    name — the registry key its sub-agent registers under. A member declaring no resolvable target
+    is a :class:`CapabilityError`, matching the "declare exactly one way" spec rule.
+    """
+    if member.a2a is not None:
+        auth = A2AAuthConfig(**member.a2a.auth.model_dump())
+        remote = RemoteSpec(
+            url=member.a2a.url,
+            card_path=member.a2a.card_path,
+            auth=auth,
+            timeout_seconds=member.a2a.timeout_seconds,
+        )
+        return AgentRef(name=member.name, remote=remote)
+    if member.ref is not None or member.prompt is not None:
+        return AgentRef(name=member.name, local_ref=member.name)
+    raise CapabilityError(
+        f"member {member.name!r} declares no resolvable target — cannot resolve it as a "
+        f"specialist; give it a ref, a prompt, or an a2a block"
+    )

agentship/a2a/card.py

@@ -0,0 +1,86 @@
+"""Generate an A2A Agent Card from an ``AgentSpec`` + the engine's real capabilities (§C4).
+
+The author never writes a card by hand. :func:`build_agent_card` reads the declarative spec and
+the engine's :class:`~agentship.engines.base.EngineCapabilities`, so every claim on the card is
+one the agent can actually honour — ``streaming`` is true only when the engine streams, the
+advertised ``securitySchemes`` are exactly the ones the service enforces. That "declare, don't
+fake" honesty is the whole point of generating rather than hand-writing (DESIGN §3 honesty).
+"""
+
+from __future__ import annotations
+
+from ..engines.base import EngineCapabilities
+from ..spec import A2aOAuth2Spec, AgentSpec
+from .models import (
+    AgentCapabilities,
+    AgentCard,
+    ClientCredentialsFlow,
+    OAuthFlows,
+    SecurityScheme,
+)
+
+#: Human-readable descriptions for the auth schemes an agent can advertise. The card names the
+#: scheme; the service enforces exactly this set (they come from one config, so they can't drift).
+_SECURITY_SCHEME_DESCRIPTIONS = {
+    "oauth2": "OAuth 2.0 bearer token (client-credentials flow).",
+    "apiKey": "Static API key in the X-API-Key header.",
+    "mtls": "Mutual TLS — a client certificate verified at the ingress.",
+}
+
+
+def _security_scheme(name: str, oauth2: A2aOAuth2Spec | None) -> SecurityScheme:
+    """Build the advertised :class:`SecurityScheme` for one scheme name in its A2A-conformant shape.
+
+    Each A2A scheme ``type`` needs different fields: ``apiKey`` must declare *where* the key travels
+    (``in: header``, ``name: X-API-Key``); ``oauth2`` must carry ``flows`` (we advertise the
+    client-credentials flow from ``oauth2`` config, or empty flows when none is given); and the
+    ``mtls`` scheme's A2A ``type`` is spelled ``mutualTLS``. The dict key stays the author's name
+    (``mtls``), only the emitted ``type`` differs.
+    """
+    description = _SECURITY_SCHEME_DESCRIPTIONS.get(name)
+    if name == "apiKey":
+        return SecurityScheme(
+            type="apiKey", name="X-API-Key", location="header", description=description
+        )
+    if name == "oauth2":
+        flows = OAuthFlows()
+        if oauth2 is not None:
+            flows = OAuthFlows(
+                client_credentials=ClientCredentialsFlow(
+                    token_url=oauth2.token_url, scopes=dict(oauth2.scopes)
+                )
+            )
+        return SecurityScheme(type="oauth2", description=description, flows=flows)
+    if name == "mtls":
+        return SecurityScheme(type="mutualTLS", description=description)
+    return SecurityScheme(type=name, description=description)
+
+
+def build_agent_card(
+    spec: AgentSpec,
+    capabilities: EngineCapabilities,
+    *,
+    base_url: str,
+    security: list[str] | None = None,
+    oauth2: A2aOAuth2Spec | None = None,
+) -> AgentCard:
+    """Build the A2A :class:`AgentCard` for ``spec`` served under ``base_url``.
+
+    ``base_url`` is the service root (e.g. ``https://host``); the card's ``url`` is the agent's
+    A2A endpoint ``{base_url}/a2a/{name}``. ``capabilities`` is the built engine's declared
+    capabilities — ``streaming`` on the card mirrors ``capabilities.streaming`` exactly, never the
+    spec's *request* to stream. ``security`` is the list of scheme names the agent enforces
+    (from its ``a2a.security`` block); each becomes both a ``securitySchemes`` entry and a
+    ``security`` requirement so the card advertises precisely what the inbound router checks.
+    ``oauth2`` supplies the token endpoint/scopes advertised on the ``oauth2`` scheme, when set.
+    """
+    root = base_url.rstrip("/")
+    schemes = {name: _security_scheme(name, oauth2) for name in (security or [])}
+    return AgentCard(
+        name=spec.name,
+        description=spec.prompt,
+        url=f"{root}/a2a/{spec.name}",
+        capabilities=AgentCapabilities(streaming=capabilities.streaming),
+        security_schemes=schemes,
+        security=[{name: []} for name in (security or [])],
+    )

agentship/a2a/client.py

@@ -0,0 +1,86 @@
+"""The A2A client: send ``message/send`` to a remote agent over a pluggable transport (§C3/C6).
+
+:class:`RemoteA2aAgent` speaks the client side of A2A — it builds the JSON-RPC envelope, attaches
+the outbound credential + tenant/trace headers, hands the request to a :class:`A2ATransport`, and
+unwraps the agent's reply. The transport is an injection seam: production uses
+:class:`HttpxTransport` (a thin ``httpx.AsyncClient`` wrapper); tests pass a fake, so the client
+logic is exercised with no network. Any transport-level failure becomes a retryable
+:class:`~agentship.errors.A2AUnavailable` — the framework never silently swaps a remote for a local.
+"""
+
+from __future__ import annotations
+
+import uuid
+from typing import Any, Protocol
+
+from ..context import RunContext
+from ..errors import A2AUnavailable, CapabilityError
+from .models import JsonRpcRequest, JsonRpcResponse, Message, RemoteSpec
+from .security import build_outbound_auth, propagation_headers
+
+
+class A2ATransport(Protocol):
+    """Carry one JSON-RPC call to ``url`` and return the parsed JSON response body."""
+
+    async def rpc(self, url: str, payload: dict, headers: dict) -> dict:  # noqa: D102 - stub
+        ...
+
+
+class HttpxTransport:
+    """The production transport: POST the JSON-RPC body with ``httpx`` (imported lazily)."""
+
+    def __init__(self, *, timeout_seconds: float = 60.0) -> None:
+        """Bind the per-call timeout; ``httpx`` is imported on first use so core stays light."""
+        self._timeout = timeout_seconds
+
+    async def rpc(self, url: str, payload: dict, headers: dict) -> dict:
+        """POST ``payload`` as JSON to ``url`` and return the decoded response body."""
+        import httpx
+
+        async with httpx.AsyncClient(timeout=self._timeout) as client:
+            resp = await client.post(url, json=payload, headers=headers)
+            resp.raise_for_status()
+            return resp.json()
+
+
+class RemoteA2aAgent:
+    """A networked specialist reached over A2A, satisfying the same ``send`` port as a local one."""
+
+    def __init__(self, remote: RemoteSpec, *, transport: A2ATransport) -> None:
+        """Bind the remote's location/auth and the transport that carries calls to it."""
+        self._remote = remote
+        self._transport = transport
+        self._auth = build_outbound_auth(remote.auth)
+
+    async def send(self, text: str, ctx: RunContext) -> str:
+        """Send one ``message/send`` turn and return the remote agent's text reply.
+
+        Builds the JSON-RPC envelope, layers the credential over the tenant/trace headers, and
+        unwraps the result Message. A transport failure or a JSON-RPC error becomes
+        :class:`A2AUnavailable` (retryable) / :class:`CapabilityError` respectively.
+        """
+        request = JsonRpcRequest(
+            id=uuid.uuid4().hex,
+            method="message/send",
+            params={"message": Message.user(text).model_dump(by_alias=True)},
+        )
+        headers = {**propagation_headers(ctx), **self._auth.headers(ctx)}
+        try:
+            raw = await self._transport.rpc(
+                self._remote.url, request.model_dump(by_alias=True), headers
+            )
+        except Exception as exc:  # noqa: BLE001 — any transport failure is a retryable A2A outage
+            raise A2AUnavailable(f"A2A call to {self._remote.url!r} failed: {exc}") from exc
+        return _unwrap(raw)
+
+
+def _unwrap(raw: dict[str, Any]) -> str:
+    """Turn a JSON-RPC response body into the agent's reply text, or raise on a protocol error."""
+    response = JsonRpcResponse.model_validate(raw)
+    if response.error is not None:
+        raise CapabilityError(
+            f"remote A2A agent returned error {response.error.code}: {response.error.message}"
+        )
+    result = response.result or {}
+    parts = result.get("parts") or []
+    return "".join(part.get("text", "") for part in parts if part.get("kind", "text") == "text")

agentship/a2a/models.py

@@ -0,0 +1,271 @@
+"""A2A wire models and the ``AgentRef`` handle (Phase 05 · C3, C4).
+
+Two families live here, both transport-agnostic (no ``httpx``/FastAPI), so they belong in core:
+
+* **Authoring models** — :class:`AgentRef` and :class:`RemoteSpec`: how an author declares a
+  specialist that may be in-process *or* networked. Exactly one target is required, validated at
+  construction so a bad YAML block fails fast at load (§C3).
+* **A2A protocol models** — :class:`AgentCard`, :class:`Message`/:class:`TextPart`, and the
+  :class:`JsonRpcRequest`/:class:`JsonRpcResponse` envelope. These mirror the A2A spec's JSON
+  shapes (camelCase on the wire via field aliases) so our server and client speak the protocol
+  without pulling in the ``a2a-sdk`` dependency; the models are deliberately a faithful subset of
+  what we implement (``message/send``, ``message/stream``, the Agent Card).
+
+We keep these thin models rather than adopting ``a2a-sdk``'s types directly, by design:
+a2a-sdk 1.x is protobuf-first (``a2a.types`` is compiled protobuf), and its only Pydantic/JSON
+representation is the legacy ``a2a.compat.v0_3`` shim — adopting either would force grpc/protobuf
+lock-in and protobuf-JSON semantics into this clean Pydantic/JSON service. Instead of importing
+their models we *validate against* them: ``agentship-service[a2a]``'s drift guard
+(``tests/test_a2a_conformance.py``) parses every shape we emit with a2a-sdk's own schema, so we
+cannot drift from the spec. That is what "integrate, don't reinvent" means here — conform to the
+standard's schema, without taking a dependency that fits this service poorly.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+from uuid import uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ..errors import CapabilityError
+
+#: The A2A protocol revision our wire models target. Pinned so a spec bump is a deliberate,
+#: reviewable change rather than a silent drift (R1 in the phase risks).
+A2A_PROTOCOL_VERSION = "0.3.0"
+
+
+# --------------------------------------------------------------------------------------------
+# Authoring models — how a specialist reference is declared (in-process or networked).
+# --------------------------------------------------------------------------------------------
+
+
+class A2AAuthConfig(BaseModel):
+    """How to authenticate an *outbound* A2A call to a remote agent (§C6).
+
+    ``type`` selects the credential injector the client builds: ``bearer`` reads a static token
+    from ``token_env``; ``oauth2`` runs client-credentials against ``token_url``; ``mtls`` uses a
+    client cert/key pair. Only the fields the chosen ``type`` needs are set; the rest stay ``None``.
+    """
+
+    type: Literal["none", "bearer", "oauth2", "mtls"] = "none"
+    #: Environment variable holding the static bearer token (``bearer``).
+    token_env: str | None = None
+    #: OAuth2 token endpoint + client credentials env vars (``oauth2``).
+    token_url: str | None = None
+    client_id_env: str | None = None
+    client_secret_env: str | None = None
+    #: Client certificate/key file paths (``mtls``).
+    cert_path: str | None = None
+    key_path: str | None = None
+
+
+class RemoteSpec(BaseModel):
+    """Where a networked specialist lives and how to reach it (§C3).
+
+    ``url`` is the remote agent's A2A base URL; its Agent Card is fetched from ``url + card_path``
+    unless a caller passes one in. ``auth`` selects the outbound credential; ``timeout_seconds``
+    bounds a synchronous consult.
+    """
+
+    url: str
+    card_path: str = "/.well-known/agent-card.json"
+    auth: A2AAuthConfig = Field(default_factory=A2AAuthConfig)
+    timeout_seconds: int = 60
+
+
+class AgentRef(BaseModel):
+    """A reference to a specialist, resolved either in-process or over A2A (§C3).
+
+    Exactly one of ``local_ref`` (a locally-registered agent name) or ``remote`` (a
+    :class:`RemoteSpec`) must be set — presence of ``remote`` means networked, presence of
+    ``local_ref`` means in-process. Both or neither is a load-time :class:`CapabilityError` so a
+    malformed ``specialists:`` block never reaches build. One reference type, two resolutions: the
+    supervisor's authoring code never branches on transport.
+    """
+
+    name: str
+    local_ref: str | None = None
+    remote: RemoteSpec | None = None
+
+    def model_post_init(self, _context: Any) -> None:
+        """Enforce the exactly-one-target rule at construction (fail-fast at load)."""
+        has_local = self.local_ref is not None
+        has_remote = self.remote is not None
+        if has_local == has_remote:
+            raise CapabilityError(
+                f"specialist {self.name!r} must set exactly one of local_ref (in-process) or "
+                f"a2a/remote (networked) — got "
+                f"{'both' if has_local else 'neither'}; fix the specialists block"
+            )
+
+    def is_remote(self) -> bool:
+        """Whether this specialist is reached over the network (A2A) rather than in-process."""
+        return self.remote is not None
+
+
+# --------------------------------------------------------------------------------------------
+# A2A protocol models — the Agent Card and the JSON-RPC message envelope.
+# --------------------------------------------------------------------------------------------
+
+
+class _A2AModel(BaseModel):
+    """Base for wire models: serialise with A2A's camelCase aliases, accept either casing in."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class AgentCapabilities(_A2AModel):
+    """The ``capabilities`` block of an Agent Card — honest flags, generated from the engine."""
+
+    streaming: bool = False
+    push_notifications: bool = Field(default=False, alias="pushNotifications")
+    state_transition_history: bool = Field(default=False, alias="stateTransitionHistory")
+
+
+class AgentSkill(_A2AModel):
+    """One advertised skill on an Agent Card (A2A ``skills[]`` entry)."""
+
+    id: str
+    name: str
+    description: str
+    tags: list[str] = Field(default_factory=list)
+
+
+class ClientCredentialsFlow(_A2AModel):
+    """The OAuth2 client-credentials flow on the card (A2A ``ClientCredentialsOAuthFlow``).
+
+    Advertised so a service-to-service caller can obtain a token on its own.
+    ``token_url`` is where a client exchanges its client id/secret for a bearer token; ``scopes``
+    maps each scope name the service accepts to a human description. A2A requires both on the flow.
+    """
+
+    token_url: str = Field(alias="tokenUrl")
+    scopes: dict[str, str] = Field(default_factory=dict)
+
+
+class OAuthFlows(_A2AModel):
+    """The set of OAuth2 flows an ``oauth2`` scheme offers (A2A ``OAuthFlows``).
+
+    We advertise only the client-credentials flow (service-to-service, which is how agents call each
+    other over A2A); the other flow slots stay unset. An empty ``OAuthFlows`` is spec-valid and is
+    what we emit when the author names ``oauth2`` without declaring a token endpoint.
+    """
+
+    client_credentials: ClientCredentialsFlow | None = Field(
+        default=None, alias="clientCredentials"
+    )
+
+
+class SecurityScheme(_A2AModel):
+    """A single accepted auth scheme on the card (A2A ``securitySchemes`` value).
+
+    We advertise exactly the schemes the service enforces (they are generated from one config so
+    the card and the inbound check can never drift — §C6). Only the fields a given ``type`` needs
+    are set; A2A ignores the unused ``None`` fields, and the drift guard proves each variant
+    validates against ``a2a-sdk``'s discriminated ``SecurityScheme`` union.
+    """
+
+    type: str
+    description: str | None = None
+    # apiKey schemes must declare WHERE the key travels so a client knows how to authenticate
+    # (A2A/OpenAPI APIKeySecurityScheme requires both). ``location`` serialises as ``in``.
+    name: str | None = None
+    location: str | None = Field(default=None, alias="in")
+    # oauth2 schemes carry the flows a client can use to obtain a token; unset for apiKey/mutualTLS.
+    flows: OAuthFlows | None = None
+
+
+class AgentCard(_A2AModel):
+    """The A2A Agent Card served at ``/.well-known/agent-card.json`` (§7, §C4).
+
+    Generated from an :class:`~agentship.spec.AgentSpec` plus the engine's real
+    :class:`~agentship.engines.base.EngineCapabilities` — never hand-written — so what the card
+    claims (streaming, skills, security) is exactly what the agent does. Serialise with
+    ``by_alias=True`` to emit the A2A camelCase field names.
+    """
+
+    name: str
+    description: str | None = None
+    url: str
+    version: str = "1.0.0"
+    protocol_version: str = Field(default=A2A_PROTOCOL_VERSION, alias="protocolVersion")
+    capabilities: AgentCapabilities = Field(default_factory=AgentCapabilities)
+    default_input_modes: list[str] = Field(
+        default_factory=lambda: ["text/plain"], alias="defaultInputModes"
+    )
+    default_output_modes: list[str] = Field(
+        default_factory=lambda: ["text/plain"], alias="defaultOutputModes"
+    )
+    skills: list[AgentSkill] = Field(default_factory=list)
+    security_schemes: dict[str, SecurityScheme] = Field(
+        default_factory=dict, alias="securitySchemes"
+    )
+    security: list[dict[str, list[str]]] = Field(default_factory=list)
+
+
+class TextPart(_A2AModel):
+    """A text ``Part`` of an A2A ``Message`` (the only part kind we speak today)."""
+
+    kind: Literal["text"] = "text"
+    text: str
+
+
+class Message(_A2AModel):
+    """An A2A ``Message``: a role plus an ordered list of parts (§C3 mapping)."""
+
+    role: Literal["user", "agent"] = "user"
+    parts: list[TextPart] = Field(default_factory=list)
+    # The A2A spec requires every Message to carry a stable id; generate one so our outbound
+    # messages are spec-conformant (verified by the schema drift guard in test_a2a_conformance).
+    message_id: str = Field(default_factory=lambda: uuid4().hex, alias="messageId")
+
+    @classmethod
+    def user(cls, text: str) -> Message:
+        """Build a single-text-part ``user`` message (the common inbound/outbound shape)."""
+        return cls(role="user", parts=[TextPart(text=text)])
+
+    @classmethod
+    def agent(cls, text: str) -> Message:
+        """Build a single-text-part ``agent`` message (a specialist's reply)."""
+        return cls(role="agent", parts=[TextPart(text=text)])
+
+    def text(self) -> str:
+        """Concatenate every text part into one string (what an engine's ``run`` consumes)."""
+        return "".join(part.text for part in self.parts)
+
+
+class JsonRpcError(_A2AModel):
+    """The ``error`` member of a JSON-RPC failure response."""
+
+    code: int
+    message: str
+    data: Any | None = None
+
+
+class JsonRpcRequest(_A2AModel):
+    """A JSON-RPC 2.0 request envelope (``message/send``, ``message/stream``, ``tasks/*``)."""
+
+    jsonrpc: Literal["2.0"] = "2.0"
+    id: str | int | None = None
+    method: str
+    params: dict[str, Any] = Field(default_factory=dict)
+
+
+class JsonRpcResponse(_A2AModel):
+    """A JSON-RPC 2.0 response envelope — exactly one of ``result`` or ``error`` is set."""
+
+    jsonrpc: Literal["2.0"] = "2.0"
+    id: str | int | None = None
+    result: Any | None = None
+    error: JsonRpcError | None = None
+
+    @classmethod
+    def ok(cls, id: str | int | None, result: Any) -> JsonRpcResponse:
+        """A success response carrying ``result``."""
+        return cls(id=id, result=result)
+
+    @classmethod
+    def fail(cls, id: str | int | None, code: int, message: str) -> JsonRpcResponse:
+        """A failure response carrying a JSON-RPC ``error``."""
+        return cls(id=id, error=JsonRpcError(code=code, message=message))

agentship/a2a/resolver.py

@@ -0,0 +1,46 @@
+"""Resolve one ``AgentRef`` into a specialist — in-process or networked (§C3).
+
+:class:`SpecialistResolver` is the single seam where a specialist reference becomes a callable. A
+``local_ref`` is looked up in the registry and wrapped as a :class:`LocalSpecialist`; a ``remote``
+block becomes a :class:`RemoteSpecialist` over an A2A client. Either way the caller gets the same
+``send`` port, so a supervisor graph never branches on transport (the transparency invariant).
+"""
+
+from __future__ import annotations
+
+from ..context import RunContext
+from ..errors import CapabilityError
+from .client import HttpxTransport, RemoteA2aAgent
+from .models import AgentRef
+from .specialist import LocalSpecialist, RemoteSpecialist, Specialist
+
+
+class SpecialistResolver:
+    """Turn an :class:`AgentRef` into a :class:`Specialist`, picking transport from the ref."""
+
+    def __init__(self, *, registry, transport=None) -> None:
+        """Bind the in-process ``registry`` (name → agent) and the A2A ``transport`` for remotes.
+
+        ``registry`` is any ``name → agent`` mapping (a plain dict works). ``transport`` is the A2A
+        transport used for networked refs; it defaults to :class:`HttpxTransport` so production
+        needs no wiring, while tests inject a fake to exercise the client without a network.
+        """
+        self._registry = registry
+        self._transport = transport if transport is not None else HttpxTransport()
+
+    def resolve(self, ref: AgentRef, ctx: RunContext) -> Specialist:
+        """Resolve ``ref`` to a specialist; fail fast on an unknown local ref.
+
+        A remote ref is bound to the A2A client here but not called until ``send`` — resolution is
+        cheap and synchronous; the network work happens on the turn.
+        """
+        if ref.is_remote():
+            remote_agent = RemoteA2aAgent(ref.remote, transport=self._transport)
+            return RemoteSpecialist(ref.name, remote_agent, ctx)
+        agent = self._registry.get(ref.local_ref)
+        if agent is None:
+            raise CapabilityError(
+                f"no agent registered as {ref.local_ref!r} — cannot resolve specialist "
+                f"{ref.name!r}; register it or fix the ref"
+            )
+        return LocalSpecialist(ref.name, agent, ctx)