openagent-control 0.1.0__py3-none-any.whl

openagent_control/adapters/audit_export/stdout.py

@@ -0,0 +1,36 @@
+"""stdout/log audit exporter. See docs/adr/0006-hexagonal-architecture-for-the-control-plane.md.
+
+v1 placeholder for the `AuditExporter` port; real deployments swap this for a
+Datadog/Grafana(-OTLP)/Splunk adapter behind the same port. The full receipt is
+serialized into the log message itself so it survives any logging formatter — an
+audit record carried only in `extra` would be dropped by the default formatter.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+
+from openagent_control.domain.models import ExecutionReceipt
+
+logger = logging.getLogger("openagent_control.audit")
+
+
+class StdoutAuditExporter:
+    def __init__(self) -> None:
+        # This adapter's contract is "receipts reach stdout". Host processes
+        # (e.g. uvicorn) configure their own loggers and leave the root logger
+        # handler-less at WARNING, which would silently drop INFO receipts —
+        # so attach a handler explicitly unless one is already present.
+        if not logger.handlers:
+            handler = logging.StreamHandler(sys.stdout)
+            handler.setFormatter(logging.Formatter("%(asctime)s %(name)s %(message)s"))
+            logger.addHandler(handler)
+            logger.setLevel(logging.INFO)
+            # propagate stays True: root-level pipelines (pytest caplog, host log
+            # shippers) still see receipts; worst case is a duplicate line, never
+            # a dropped one.
+
+    async def export(self, receipt: ExecutionReceipt) -> None:
+        logger.info("audit_receipt %s", json.dumps(receipt.model_dump(mode="json"), sort_keys=True))

openagent_control/adapters/db/session.py

@@ -0,0 +1,26 @@
+"""Async SQLAlchemy engine/session factory shared by the Postgres adapters."""
+
+from __future__ import annotations
+
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_sessionmaker,
+    create_async_engine,
+)
+
+from openagent_control.adapters.db.tables import SCHEMA
+
+
+def make_engine(database_url: str) -> AsyncEngine:
+    engine = create_async_engine(database_url, pool_pre_ping=True)
+    if database_url.startswith("sqlite"):
+        # SQLite has no schema concept equivalent to Postgres's CREATE SCHEMA;
+        # map the `oac` schema declared on Base.metadata down to "no schema" so
+        # the same ORM models work against an in-memory SQLite test database.
+        engine = engine.execution_options(schema_translate_map={SCHEMA: None})
+    return engine
+
+
+def make_session_factory(engine: AsyncEngine) -> async_sessionmaker[AsyncSession]:
+    return async_sessionmaker(engine, expire_on_commit=False)

openagent_control/adapters/db/tables.py

@@ -0,0 +1,68 @@
+"""SQLAlchemy table definitions backing the Postgres registry and ledger (ADR-0009).
+
+Plain `JSON` (not Postgres `JSONB`) so the same schema runs against SQLite in
+tests without a real Postgres server. `Alembic` migrations in migrations/ create
+these tables against whatever database the operator points `database_url` at.
+"""
+
+from __future__ import annotations
+
+import datetime
+
+from sqlalchemy import JSON, DateTime, Integer, MetaData, String
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+SCHEMA = "oac"
+
+
+class Base(DeclarativeBase):
+    """All tables live in the `oac` Postgres schema, not `public` — keeps the
+    control plane's tables isolated from whatever else lives in the operator's
+    database. The Alembic migration creates the schema (`CREATE SCHEMA IF NOT
+    EXISTS oac`) before creating tables in it. Tests run against SQLite via a
+    schema_translate_map (see adapters/db/session.py) since SQLite has no
+    equivalent concept."""
+
+    metadata = MetaData(schema=SCHEMA)
+
+
+class AgentRow(Base):
+    __tablename__ = "agents"
+
+    spiffe_id: Mapped[str] = mapped_column(String, primary_key=True)
+    display_name: Mapped[str] = mapped_column(String, nullable=False)
+    purpose: Mapped[str] = mapped_column(String, nullable=False)
+    owner: Mapped[str] = mapped_column(String, nullable=False)
+    risk_tier: Mapped[str] = mapped_column(String, nullable=False)
+    status: Mapped[str] = mapped_column(String, nullable=False, default="active")
+    granted_tools: Mapped[list[str]] = mapped_column(JSON, nullable=False, default=list)
+    created_at: Mapped[datetime.datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    updated_at: Mapped[datetime.datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    status_changed_at: Mapped[datetime.datetime | None] = mapped_column(
+        DateTime(timezone=True), nullable=True
+    )
+
+
+class ReceiptRow(Base):
+    __tablename__ = "execution_receipts"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    sequence_id: Mapped[str] = mapped_column(String, nullable=False, unique=True)
+    timestamp: Mapped[datetime.datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    spiffe_id: Mapped[str] = mapped_column(String, nullable=False, index=True)
+    decision: Mapped[str] = mapped_column(String, nullable=False)
+    reason: Mapped[str] = mapped_column(String, nullable=False, default="")
+    payload_hash: Mapped[str] = mapped_column(String, nullable=False)
+    previous_hash: Mapped[str] = mapped_column(String, nullable=False)
+    signature: Mapped[str] = mapped_column(String, nullable=False)
+
+
+class ChainStateRow(Base):
+    """Singleton row (id=1) holding the current chain head. Locked with
+    SELECT ... FOR UPDATE inside the same transaction as a receipt insert so
+    concurrent writers across replicas serialize instead of racing."""
+
+    __tablename__ = "chain_state"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    previous_hash: Mapped[str] = mapped_column(String, nullable=False)

openagent_control/adapters/identity/header.py

@@ -0,0 +1,24 @@
+"""Header-trusting identity adapter. See docs/adr/0005.
+
+NOT a security boundary on its own: it trusts whatever `X-Spiffe-ID` header is
+present. Only safe behind a network layer (e.g. a service mesh) that has already
+performed real SPIFFE/mTLS attestation. Swap for a SPIRE Workload API adapter before
+this is exposed to anything untrusted.
+"""
+
+from __future__ import annotations
+
+from openagent_control.domain.errors import IdentityError
+from openagent_control.domain.models import AgentIdentity
+
+_SPIFFE_HEADER = "x-spiffe-id"
+_SPONSOR_HEADER = "x-human-sponsor"
+
+
+class HeaderIdentityProvider:
+    async def identify(self, raw_headers: dict[str, str]) -> AgentIdentity:
+        headers = {k.lower(): v for k, v in raw_headers.items()}
+        spiffe_id = headers.get(_SPIFFE_HEADER)
+        if not spiffe_id:
+            raise IdentityError(f"missing required '{_SPIFFE_HEADER}' header")
+        return AgentIdentity(spiffe_id=spiffe_id, human_sponsor=headers.get(_SPONSOR_HEADER))

openagent_control/adapters/identity/jwt_svid.py

@@ -0,0 +1,74 @@
+"""JWT-SVID identity adapter: cryptographic workload identity (ADR-0005).
+
+Validates a SPIFFE JWT-SVID presented as `Authorization: Bearer <token>`:
+signature against the trust-domain public key, audience, and expiry; the SPIFFE
+ID is the token's `sub` claim. SPIRE issues exactly this token shape via its
+Workload API (`spire-agent api fetch jwt`), so pointing `public_key_path` at the
+trust bundle key makes this the production identity path — unlike the header
+adapter, callers cannot claim an identity they cannot prove.
+
+The per-request human sponsor stays a header (`X-Human-Sponsor`): it is an
+assertion about delegation context, verified separately via the subject-token
+exchange (ADR-0004), not part of workload identity.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import jwt
+from cryptography.hazmat.primitives.asymmetric.ec import EllipticCurvePublicKey
+from cryptography.hazmat.primitives.asymmetric.ed448 import Ed448PublicKey
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from cryptography.hazmat.primitives.asymmetric.rsa import RSAPublicKey
+from cryptography.hazmat.primitives.serialization import load_pem_public_key
+
+from openagent_control.domain.errors import IdentityError
+from openagent_control.domain.models import AgentIdentity
+
+_SPONSOR_HEADER = "x-human-sponsor"
+_ALGORITHMS = ["RS256", "ES256", "EdDSA"]
+_SUPPORTED_KEY_TYPES = (RSAPublicKey, EllipticCurvePublicKey, Ed25519PublicKey, Ed448PublicKey)
+
+
+class JwtSvidIdentityProvider:
+    def __init__(self, public_key_path: str | Path, audience: str) -> None:
+        # Parse the PEM once at startup: handing PyJWT the raw PEM string makes
+        # it re-parse the key on every decode (~56µs/request measured for
+        # RSA-2048); a preloaded key object cuts verification ~3x. Rejecting
+        # unsupported key types here turns a bad trust-bundle config into a
+        # startup failure instead of a per-request one.
+        key = load_pem_public_key(Path(public_key_path).read_bytes())
+        if not isinstance(key, _SUPPORTED_KEY_TYPES):
+            raise ValueError(
+                f"unsupported trust-bundle key type {type(key).__name__}; "
+                f"expected one usable with {_ALGORITHMS}"
+            )
+        self._public_key: (
+            RSAPublicKey | EllipticCurvePublicKey | Ed25519PublicKey | Ed448PublicKey
+        ) = key
+        self._audience = audience
+
+    async def identify(self, raw_headers: dict[str, str]) -> AgentIdentity:
+        headers = {k.lower(): v for k, v in raw_headers.items()}
+        authorization = headers.get("authorization", "")
+        scheme, _, token = authorization.partition(" ")
+        if scheme.lower() != "bearer" or not token:
+            raise IdentityError("missing 'Authorization: Bearer <jwt-svid>' header")
+
+        try:
+            claims = jwt.decode(
+                token,
+                key=self._public_key,
+                algorithms=_ALGORITHMS,
+                audience=self._audience,
+                options={"require": ["sub", "exp", "aud"]},
+            )
+        except jwt.InvalidTokenError as exc:
+            raise IdentityError(f"invalid JWT-SVID: {exc}") from exc
+
+        spiffe_id = str(claims["sub"])
+        if not spiffe_id.startswith("spiffe://"):
+            raise IdentityError(f"token subject is not a SPIFFE ID: {spiffe_id!r}")
+
+        return AgentIdentity(spiffe_id=spiffe_id, human_sponsor=headers.get(_SPONSOR_HEADER))

openagent_control/adapters/identity/oidc_jwks.py

@@ -0,0 +1,121 @@
+"""OIDC/JWKS identity adapter for Okta and Microsoft Entra ID. See ADR-0010 and
+the `enterprise-idp-integration` skill this was built from.
+
+Validates an access token actually issued by an OIDC-compliant IdP: fetches
+the discovery document once at startup, verifies signature/issuer/audience via
+a cached, rotation-aware JWKS client, and derives the calling workload's
+identity from the client/app-id claim (azp/appid/cid) rather than `sub` —
+machine (client-credentials) tokens identify the calling application that way.
+
+A `sub` claim is treated as a delegated human sponsor only when the token is
+not an app-only token; see `_has_human_sponsor`, which encodes each provider's
+documented marker. Verified against a real Keycloak realm — see
+tests/integration/test_keycloak_conformance.py.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+import httpx
+import jwt
+from jwt import PyJWKClient
+
+from openagent_control.domain.errors import IdentityError
+from openagent_control.domain.models import AgentIdentity
+
+_SPONSOR_HEADER = "x-human-sponsor"
+_ALGORITHMS = ["RS256"]
+# Claims that identify the calling application/service principal, checked in
+# order — see ADR-0010 on why this isn't simply `sub`.
+_CLIENT_ID_CLAIMS = ("azp", "appid", "cid")
+
+# Keycloak issues client-credentials tokens with `sub` set to the service
+# account's UUID — distinct from the client id — so "sub differs from the
+# client" is not on its own evidence of a human. Each provider marks app-only
+# tokens differently; these are the documented markers:
+_KEYCLOAK_SERVICE_ACCOUNT_PREFIX = "service-account-"
+_ENTRA_APP_ONLY_IDTYP = "app"
+
+
+def _has_human_sponsor(claims: dict[str, object], client_id: str) -> bool:
+    """True only when the token really represents a user acting through the agent.
+
+    Getting this wrong is not cosmetic: a false positive makes the gateway treat
+    an autonomous machine call as delegated and reject it for a missing subject
+    token, which is exactly what happened against a real Keycloak realm before
+    this check existed.
+    """
+    subject = claims.get("sub")
+    if not subject or subject == client_id:  # Okta client-credentials
+        return False
+    if claims.get("idtyp") == _ENTRA_APP_ONLY_IDTYP:  # Entra app-only token
+        return False
+    username = claims.get("preferred_username")  # Keycloak service account
+    return not (isinstance(username, str) and username.startswith(_KEYCLOAK_SERVICE_ACCOUNT_PREFIX))
+
+
+class OidcJwksIdentityProvider:
+    def __init__(
+        self,
+        discovery_url: str,
+        audience: str,
+        issuer: str = "",
+        client: httpx.Client | None = None,
+    ) -> None:
+        # Fetched once at construction (startup), not lazily: a bad discovery
+        # URL/document becomes a startup failure, not a per-request one — same
+        # posture as the JWT-SVID trust-bundle key (ADR-0005).
+        owns_client = client is None
+        discovery_client = client or httpx.Client(timeout=10.0)
+        try:
+            discovery = discovery_client.get(discovery_url)
+            discovery.raise_for_status()
+            document = discovery.json()
+        finally:
+            if owns_client:
+                discovery_client.close()
+
+        self._jwks_client = PyJWKClient(document["jwks_uri"])
+        self._audience = audience
+        self._issuer = issuer or document["issuer"]
+
+    async def identify(self, raw_headers: dict[str, str]) -> AgentIdentity:
+        headers = {k.lower(): v for k, v in raw_headers.items()}
+        authorization = headers.get("authorization", "")
+        scheme, _, token = authorization.partition(" ")
+        if scheme.lower() != "bearer" or not token:
+            raise IdentityError("missing 'Authorization: Bearer <access-token>' header")
+
+        try:
+            claims = await asyncio.to_thread(self._verify, token)
+        except jwt.InvalidTokenError as exc:
+            raise IdentityError(f"invalid OIDC access token: {exc}") from exc
+
+        client_id = next((str(claims[c]) for c in _CLIENT_ID_CLAIMS if c in claims), None)
+        if not client_id:
+            raise IdentityError(
+                f"token has none of the expected client-id claims {_CLIENT_ID_CLAIMS}"
+            )
+
+        human_sponsor = str(claims["sub"]) if _has_human_sponsor(claims, client_id) else None
+
+        return AgentIdentity(
+            spiffe_id=f"oidc://{self._issuer}/{client_id}",
+            human_sponsor=human_sponsor or headers.get(_SPONSOR_HEADER),
+        )
+
+    def _verify(self, token: str) -> dict[str, object]:
+        # Runs in a worker thread (see identify()): PyJWKClient performs a
+        # blocking HTTP call on a JWKS cache miss (key rotation), which would
+        # otherwise stall the event loop for every concurrent request.
+        signing_key = self._jwks_client.get_signing_key_from_jwt(token)
+        claims: dict[str, object] = jwt.decode(
+            token,
+            key=signing_key.key,
+            algorithms=_ALGORITHMS,
+            audience=self._audience,
+            issuer=self._issuer,
+            options={"require": ["iss", "aud", "exp"]},
+        )
+        return claims

openagent_control/adapters/ledger/ed25519_chain.py

@@ -0,0 +1,57 @@
+"""In-memory Ed25519 hash-chained ledger adapter. See docs/adr/0003.
+
+Known v1 limitations (tracked in the ADR, not solved here — PostgresLedger in
+adapters/ledger/postgres.py addresses both per ADR-0009):
+- the signing key is generated in-process and lost on restart;
+- chain state (`_previous_hash`) lives in a single process's memory, so this does
+  not scale to multiple replicas without a shared, race-safe store.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import uuid
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+
+from openagent_control.adapters.ledger.signing import GENESIS_HASH, ReceiptSigner, canonical_json
+from openagent_control.domain.models import (
+    AgentIdentity,
+    ExecutionReceipt,
+    PolicyDecision,
+    ToolCallRequest,
+)
+
+
+class Ed25519ChainLedger:
+    def __init__(self, private_key: Ed25519PrivateKey | None = None) -> None:
+        self._signer = ReceiptSigner(private_key)
+        self._previous_hash = GENESIS_HASH
+        self._lock = asyncio.Lock()
+
+    def public_key(self) -> Ed25519PublicKey:
+        """The verification key for receipts signed by this ledger instance."""
+        return self._signer.public_key()
+
+    async def record(
+        self, agent: AgentIdentity, request: ToolCallRequest, decision: PolicyDecision
+    ) -> ExecutionReceipt:
+        payload_hash = hashlib.sha256(canonical_json(request.model_dump(mode="json"))).hexdigest()
+
+        async with self._lock:
+            receipt = ExecutionReceipt(
+                sequence_id=str(uuid.uuid4()),
+                spiffe_id=agent.spiffe_id,
+                decision=decision.decision,
+                reason=decision.reason,
+                payload_hash=payload_hash,
+                previous_hash=self._previous_hash,
+            )
+            unsigned_bytes = canonical_json(receipt.model_dump(mode="json", exclude={"signature"}))
+            signature = self._signer.sign(unsigned_bytes)
+            receipt.signature = signature.hex()
+
+            self._previous_hash = hashlib.sha256(unsigned_bytes + signature).hexdigest()
+
+        return receipt

openagent_control/adapters/ledger/postgres.py

@@ -0,0 +1,77 @@
+"""Postgres-backed hash-chained ledger. See docs/adr/0009.
+
+Closes both gaps ADR-0003 flagged: the signing key is provided by the caller
+(sourced from wherever the operator's KMS/secret store puts it — this adapter
+does not generate or persist it), and chain state is a database row, correct
+across multiple gateway replicas because `record()` takes a row lock on the
+chain head inside the same transaction as the receipt insert.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import uuid
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+
+from openagent_control.adapters.db.tables import ChainStateRow, ReceiptRow
+from openagent_control.adapters.ledger.signing import ReceiptSigner, canonical_json
+from openagent_control.domain.models import (
+    AgentIdentity,
+    ExecutionReceipt,
+    PolicyDecision,
+    ToolCallRequest,
+)
+
+
+class PostgresLedger:
+    def __init__(
+        self, session_factory: async_sessionmaker[AsyncSession], signer: ReceiptSigner
+    ) -> None:
+        self._session_factory = session_factory
+        self._signer = signer
+
+    def public_key(self) -> Ed25519PublicKey:
+        return self._signer.public_key()
+
+    async def record(
+        self, agent: AgentIdentity, request: ToolCallRequest, decision: PolicyDecision
+    ) -> ExecutionReceipt:
+        payload_hash = hashlib.sha256(canonical_json(request.model_dump(mode="json"))).hexdigest()
+
+        async with self._session_factory() as session, session.begin():
+            chain_state = (
+                await session.execute(
+                    select(ChainStateRow).where(ChainStateRow.id == 1).with_for_update()
+                )
+            ).scalar_one()
+
+            receipt = ExecutionReceipt(
+                sequence_id=str(uuid.uuid4()),
+                spiffe_id=agent.spiffe_id,
+                decision=decision.decision,
+                reason=decision.reason,
+                payload_hash=payload_hash,
+                previous_hash=chain_state.previous_hash,
+            )
+            unsigned_bytes = canonical_json(receipt.model_dump(mode="json", exclude={"signature"}))
+            signature = self._signer.sign(unsigned_bytes)
+            receipt.signature = signature.hex()
+
+            session.add(
+                ReceiptRow(
+                    sequence_id=receipt.sequence_id,
+                    timestamp=receipt.timestamp,
+                    spiffe_id=receipt.spiffe_id,
+                    decision=receipt.decision.value,
+                    reason=receipt.reason,
+                    payload_hash=receipt.payload_hash,
+                    previous_hash=receipt.previous_hash,
+                    signature=receipt.signature,
+                )
+            )
+            chain_state.previous_hash = hashlib.sha256(unsigned_bytes + signature).hexdigest()
+
+        return receipt

openagent_control/adapters/ledger/signing.py

@@ -0,0 +1,30 @@
+"""Shared Ed25519 receipt-signing logic used by every ledger adapter.
+
+Extracted so the in-memory (Ed25519ChainLedger) and Postgres (PostgresLedger)
+adapters sign identically instead of duplicating canonical-JSON/crypto code —
+see ADR-0009.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+
+GENESIS_HASH = "0" * 64
+
+
+def canonical_json(data: dict[str, Any]) -> bytes:
+    return json.dumps(data, sort_keys=True, default=str).encode("utf-8")
+
+
+class ReceiptSigner:
+    def __init__(self, private_key: Ed25519PrivateKey | None = None) -> None:
+        self._private_key = private_key or Ed25519PrivateKey.generate()
+
+    def sign(self, unsigned_bytes: bytes) -> bytes:
+        return self._private_key.sign(unsigned_bytes)
+
+    def public_key(self) -> Ed25519PublicKey:
+        return self._private_key.public_key()

openagent_control/adapters/mcp_upstream/http.py

@@ -0,0 +1,40 @@
+"""HTTP MCP upstream adapter — forwards an approved tools/call to a downstream MCP server.
+
+Real target adapters (Intapp DealCloud, other MCP servers) point this same
+implementation at a different `upstream_url`; no new adapter code is needed unless a
+target requires a non-standard request shape.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+from openagent_control.domain.errors import UpstreamError
+from openagent_control.domain.models import ToolCallRequest
+
+
+class HttpMCPUpstream:
+    def __init__(self, upstream_url: str, client: httpx.AsyncClient | None = None) -> None:
+        self._upstream_url = upstream_url
+        self._client = client or httpx.AsyncClient(timeout=10.0)
+
+    async def forward(self, request: ToolCallRequest, credential: str) -> dict[str, Any]:
+        payload = {
+            "jsonrpc": "2.0",
+            "id": request.request_id,
+            "method": request.method,
+            "params": {"name": request.tool_name, "arguments": request.arguments},
+        }
+        headers = {"Authorization": f"Bearer {credential}"}
+        try:
+            response = await self._client.post(self._upstream_url, json=payload, headers=headers)
+            response.raise_for_status()
+        except httpx.HTTPError as exc:
+            raise UpstreamError(str(exc)) from exc
+        result: dict[str, Any] = response.json()
+        return result
+
+    async def aclose(self) -> None:
+        await self._client.aclose()

openagent_control/adapters/mcp_upstream/streamable_http.py

@@ -0,0 +1,93 @@
+"""MCP Streamable HTTP upstream adapter, built on the official MCP Python SDK.
+
+`HttpMCPUpstream` POSTs a bare JSON-RPC body, which is *not* the MCP transport.
+A real MCP server rejects that with `406 Not Acceptable` (the client must accept
+both `application/json` and `text/event-stream`) and then `400 Missing session
+ID` (Streamable HTTP requires an `initialize` handshake first). Rather than
+re-implement handshake, session management and SSE framing here, this adapter
+delegates all of it to `mcp.ClientSession` + `mcp.client.streamable_http` — the
+reference implementation maintained alongside the specification.
+
+Credential handling follows the MCP authorization spec (2025-06-18): the
+brokered credential is sent as `Authorization: Bearer`, and it is a token the
+gateway obtained for the *upstream's own* audience — never the agent's token.
+The spec explicitly forbids token passthrough, and audience-scoped brokering
+(ADR-0004) is precisely what satisfies that requirement.
+
+Session lifecycle: one MCP session per tool call. That costs an extra
+initialize round trip compared with pooling sessions, and is a deliberate v1
+tradeoff — a pooled session is stateful, must be rebuilt when the upstream
+restarts, and needs its own concurrency control. See ADR-0011.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+from mcp import ClientSession
+from mcp.client.streamable_http import streamable_http_client
+
+from openagent_control.domain.errors import UpstreamError
+from openagent_control.domain.models import ToolCallRequest
+
+
+class StreamableHttpMCPUpstream:
+    def __init__(self, upstream_url: str, timeout: float = 30.0) -> None:
+        self._upstream_url = upstream_url
+        self._timeout = timeout
+
+    async def forward(self, request: ToolCallRequest, credential: str) -> dict[str, Any]:
+        headers = {"Authorization": f"Bearer {credential}"}
+        try:
+            async with (
+                httpx.AsyncClient(headers=headers, timeout=self._timeout) as http_client,
+                streamable_http_client(self._upstream_url, http_client=http_client) as streams,
+                ClientSession(streams[0], streams[1]) as session,
+            ):
+                await session.initialize()
+                return await self._dispatch(session, request)
+        # No `except UpstreamError: raise` here: an UpstreamError raised inside
+        # the session is re-wrapped by anyio's task group before it reaches this
+        # frame, so that branch would be unreachable. `_describe` unwraps it.
+        except Exception as exc:  # noqa: BLE001 — SDK surfaces many error types
+            raise UpstreamError(_describe(exc)) from exc
+
+    async def _dispatch(self, session: ClientSession, request: ToolCallRequest) -> dict[str, Any]:
+        if request.method == "tools/list":
+            listing = await session.list_tools()
+            return _jsonrpc_result(request, listing.model_dump(mode="json"))
+
+        result = await session.call_tool(request.tool_name or "", request.arguments or {})
+        payload = result.model_dump(mode="json")
+        if result.isError:
+            raise UpstreamError(_error_text(payload))
+        return _jsonrpc_result(request, payload)
+
+
+def _describe(exc: BaseException) -> str:
+    """Renders an SDK failure into something an agent can act on.
+
+    The SDK runs the session in an anyio task group, so failures surface as
+    `ExceptionGroup: unhandled errors in a TaskGroup (1 sub-exception)` — which
+    tells the agent (and the on-call engineer) nothing. Unwrap to the real
+    causes, since this message is what the denial payload carries back.
+    """
+    if isinstance(exc, BaseExceptionGroup):
+        return "; ".join(_describe(inner) for inner in exc.exceptions)
+    # Our own error raised inside the session's task group gets wrapped on the
+    # way out; don't re-label it with its own class name.
+    if isinstance(exc, UpstreamError):
+        return str(exc)
+    return f"{type(exc).__name__}: {exc}"
+
+
+def _jsonrpc_result(request: ToolCallRequest, payload: dict[str, Any]) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": request.request_id, "result": payload}
+
+
+def _error_text(payload: dict[str, Any]) -> str:
+    """Flattens an MCP error result's content blocks into one message."""
+    blocks = payload.get("content") or []
+    texts = [b.get("text", "") for b in blocks if isinstance(b, dict) and b.get("type") == "text"]
+    return "; ".join(t for t in texts if t) or "upstream reported an error"