macp-sdk-python 0.2.1__py3-none-any.whl

macp_sdk/agent/strategies.py

@@ -0,0 +1,312 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from ..envelope import infer_outcome_positive
+from .types import HandlerContext, IncomingMessage, MessageHandler, SessionInfo
+
+# ── Evaluation ───────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class EvaluationResult:
+    """Result of evaluating a proposal."""
+
+    recommendation: str
+    confidence: float
+    reason: str
+
+
+class EvaluationStrategy(Protocol):
+    """Protocol for evaluating proposals."""
+
+    def evaluate(self, proposal: dict[str, Any], context: SessionInfo) -> EvaluationResult: ...
+
+
+_VALID_RECOMMENDATIONS = frozenset({"APPROVE", "REVIEW", "BLOCK", "REJECT"})
+
+
+def evaluation_handler(strategy: EvaluationStrategy) -> MessageHandler:
+    """Create a MessageHandler that evaluates proposals using the given strategy.
+
+    When a ``Proposal`` message arrives, the strategy's ``evaluate()``
+    method is called and the result is logged via the handler context.
+    The caller can inspect the result via the context's projection.
+    """
+
+    def handler(message: IncomingMessage, ctx: HandlerContext) -> None:
+        result = strategy.evaluate(message.payload, ctx.session)
+        recommendation = result.recommendation.upper()
+        if recommendation not in _VALID_RECOMMENDATIONS:
+            raise ValueError(
+                f"invalid recommendation {result.recommendation!r}: "
+                "must be one of APPROVE, REVIEW, BLOCK, REJECT"
+            )
+        if not (0.0 <= result.confidence <= 1.0):
+            raise ValueError(f"confidence must be in [0.0, 1.0], got {result.confidence}")
+        ctx.log(
+            "evaluation: recommendation=%s confidence=%.2f reason=%s",
+            recommendation,
+            result.confidence,
+            result.reason,
+        )
+        proposal_id = message.proposal_id or message.payload.get("proposal_id", "")
+        ctx.actions.evaluate(
+            proposal_id,
+            recommendation,
+            confidence=result.confidence,
+            reason=result.reason,
+        )
+
+    return handler
+
+
+def function_evaluator(
+    fn: Callable[[dict[str, Any], SessionInfo], EvaluationResult],
+) -> EvaluationStrategy:
+    """Wrap a plain function as an EvaluationStrategy."""
+
+    class _FnEvaluator:
+        __slots__ = ("_fn",)
+
+        def __init__(self, fn: Callable[[dict[str, Any], SessionInfo], EvaluationResult]) -> None:
+            self._fn = fn
+
+        def evaluate(self, proposal: dict[str, Any], context: SessionInfo) -> EvaluationResult:
+            return self._fn(proposal, context)
+
+    return _FnEvaluator(fn)
+
+
+# ── Voting ───────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class VoteDecision:
+    """Result of a voting decision."""
+
+    vote: str
+    reason: str
+
+
+class VotingStrategy(Protocol):
+    """Protocol for deciding how to vote."""
+
+    def should_vote(self, projection: Any) -> bool: ...
+
+    def decide_vote(self, projection: Any) -> VoteDecision: ...
+
+
+def voting_handler(strategy: VotingStrategy) -> MessageHandler:
+    """Create a MessageHandler that makes voting decisions using the given strategy.
+
+    When any message arrives, the strategy checks whether it should vote
+    (via ``should_vote()``).  If so, ``decide_vote()`` is called and the
+    decision is logged.
+    """
+
+    def handler(message: IncomingMessage, ctx: HandlerContext) -> None:
+        if not strategy.should_vote(ctx.projection):
+            return
+        decision = strategy.decide_vote(ctx.projection)
+        ctx.log(
+            "vote: vote=%s reason=%s",
+            decision.vote,
+            decision.reason,
+        )
+        proposal_id = message.proposal_id or message.payload.get("proposal_id", "")
+        ctx.actions.vote(
+            proposal_id,
+            decision.vote,
+            reason=decision.reason,
+        )
+
+    return handler
+
+
+def function_voter(
+    should_vote_fn: Callable[[Any], bool],
+    decide_fn: Callable[[Any], VoteDecision],
+) -> VotingStrategy:
+    """Wrap plain functions as a VotingStrategy."""
+
+    class _FnVoter:
+        __slots__ = ("_decide_fn", "_should_fn")
+
+        def __init__(
+            self,
+            should_fn: Callable[[Any], bool],
+            decide_fn: Callable[[Any], VoteDecision],
+        ) -> None:
+            self._should_fn = should_fn
+            self._decide_fn = decide_fn
+
+        def should_vote(self, projection: Any) -> bool:
+            return self._should_fn(projection)
+
+        def decide_vote(self, projection: Any) -> VoteDecision:
+            return self._decide_fn(projection)
+
+    return _FnVoter(should_vote_fn, decide_fn)
+
+
+# ── Commitment ───────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class CommitmentDecision:
+    """Result of a commitment decision."""
+
+    action: str
+    authority_scope: str
+    reason: str
+    outcome_positive: bool = True
+
+
+class CommitmentStrategy(Protocol):
+    """Protocol for deciding whether and how to commit."""
+
+    def should_commit(self, projection: Any) -> bool: ...
+
+    def decide_commitment(self, projection: Any) -> CommitmentDecision: ...
+
+
+def commitment_handler(strategy: CommitmentStrategy) -> MessageHandler:
+    """Create a MessageHandler that makes commitment decisions using the given strategy.
+
+    When any message arrives, the strategy checks whether a commitment
+    should be made (via ``should_commit()``).  If so, ``decide_commitment()``
+    is called and the decision is logged.
+    """
+
+    def handler(_message: IncomingMessage, ctx: HandlerContext) -> None:
+        # commitment decisions are projection-driven; the triggering message
+        # itself isn't read, but the signature must match MessageHandler.
+        if not strategy.should_commit(ctx.projection):
+            return
+        decision = strategy.decide_commitment(ctx.projection)
+        ctx.log(
+            "commitment: action=%s scope=%s reason=%s",
+            decision.action,
+            decision.authority_scope,
+            decision.reason,
+        )
+        ctx.actions.commit(
+            decision.action,
+            decision.authority_scope,
+            reason=decision.reason,
+            outcome_positive=decision.outcome_positive,
+        )
+
+    return handler
+
+
+def function_committer(
+    should_commit_fn: Callable[[Any], bool],
+    decide_fn: Callable[[Any], CommitmentDecision],
+) -> CommitmentStrategy:
+    """Wrap plain functions as a CommitmentStrategy."""
+
+    class _FnCommitter:
+        __slots__ = ("_decide_fn", "_should_fn")
+
+        def __init__(
+            self,
+            should_fn: Callable[[Any], bool],
+            decide_fn: Callable[[Any], CommitmentDecision],
+        ) -> None:
+            self._should_fn = should_fn
+            self._decide_fn = decide_fn
+
+        def should_commit(self, projection: Any) -> bool:
+            return self._should_fn(projection)
+
+        def decide_commitment(self, projection: Any) -> CommitmentDecision:
+            return self._decide_fn(projection)
+
+    return _FnCommitter(should_commit_fn, decide_fn)
+
+
+# ── Built-in strategy factories ─────────────────────────────────────
+
+
+def majority_voter(
+    *,
+    positive_threshold: float = 0.5,
+) -> VotingStrategy:
+    """Built-in voting strategy that votes ``approve`` when the majority winner
+    matches the first proposal option, based on the decision projection.
+
+    Args:
+        positive_threshold: Fraction of votes required to trigger voting
+            (default ``0.5``).
+    """
+
+    class _MajorityVoter:
+        __slots__ = ("_threshold",)
+
+        def __init__(self, threshold: float) -> None:
+            self._threshold = threshold
+
+        def should_vote(self, projection: Any) -> bool:
+            if projection is None:
+                return False
+            totals = projection.vote_totals()
+            total_votes = sum(totals.values())
+            return total_votes > 0 and any(
+                count / total_votes >= self._threshold for count in totals.values()
+            )
+
+        def decide_vote(self, projection: Any) -> VoteDecision:
+            winner = projection.majority_winner()
+            if winner:
+                return VoteDecision(vote="APPROVE", reason=f"majority winner: {winner}")
+            return VoteDecision(vote="ABSTAIN", reason="no majority winner")
+
+    return _MajorityVoter(positive_threshold)
+
+
+def majority_committer(
+    *,
+    quorum_size: int = 1,
+    action: str = "commit",
+    authority_scope: str = "session",
+) -> CommitmentStrategy:
+    """Built-in commitment strategy that commits when a majority winner exists
+    and the quorum has been met.
+
+    Args:
+        quorum_size: Minimum number of votes before commitment (default ``1``).
+        action: The commitment action string (default ``"commit"``).
+        authority_scope: The commitment authority scope (default ``"session"``).
+    """
+
+    class _MajorityCommitter:
+        __slots__ = ("_action", "_quorum", "_scope")
+
+        def __init__(self, quorum: int, commit_action: str, scope: str) -> None:
+            self._quorum = quorum
+            self._action = commit_action
+            self._scope = scope
+
+        def should_commit(self, projection: Any) -> bool:
+            if projection is None:
+                return False
+            totals = projection.vote_totals()
+            total_votes = sum(totals.values())
+            if total_votes < self._quorum:
+                return False
+            return projection.majority_winner() is not None
+
+        def decide_commitment(self, projection: Any) -> CommitmentDecision:
+            winner = projection.majority_winner()
+            return CommitmentDecision(
+                action=self._action,
+                authority_scope=self._scope,
+                reason=f"majority winner: {winner}",
+                outcome_positive=infer_outcome_positive(self._action),
+            )
+
+    return _MajorityCommitter(quorum_size, action, authority_scope)

macp_sdk/agent/transports.py

@@ -0,0 +1,153 @@
+"""Transport adapters for the agent event loop.
+
+Provides a :class:`TransportAdapter` protocol and two implementations:
+
+- :class:`GrpcTransportAdapter` — uses a bidirectional ``StreamSession`` RPC.
+- :class:`HttpTransportAdapter` — polls an HTTP endpoint for new envelopes.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Iterator
+from typing import Any, Protocol
+
+from .._logging import logger
+from ..auth import AuthConfig
+from ..client import MacpClient
+from .types import IncomingMessage
+
+
+class TransportAdapter(Protocol):
+    """Protocol for delivering session envelopes to a Participant."""
+
+    def start(self) -> Iterator[IncomingMessage]:
+        """Yield incoming messages from the transport."""
+        ...
+
+    def stop(self) -> None:
+        """Signal the transport to stop delivering messages."""
+        ...
+
+
+class GrpcTransportAdapter:
+    """Delivers messages via the bidirectional ``StreamSession`` gRPC RPC."""
+
+    def __init__(
+        self,
+        client: MacpClient,
+        session_id: str,
+        *,
+        auth: AuthConfig | None = None,
+        timeout: float | None = None,
+    ) -> None:
+        self._client = client
+        self._session_id = session_id
+        self._auth = auth
+        self._timeout = timeout
+        self._stream: Any = None
+        self._stopped = False
+
+    def start(self) -> Iterator[IncomingMessage]:
+        """Open a stream and yield messages for the target session."""
+        self._stream = self._client.open_stream(auth=self._auth, timeout=self._timeout)
+        try:
+            for envelope in self._stream.responses():
+                if self._stopped:
+                    break
+                if envelope.session_id != self._session_id:
+                    continue
+                yield _envelope_to_message(envelope)
+        finally:
+            if self._stream is not None:
+                self._stream.close()
+
+    def stop(self) -> None:
+        self._stopped = True
+        if self._stream is not None:
+            self._stream.close()
+
+
+class HttpTransportAdapter:
+    """Delivers messages by polling an HTTP endpoint for new envelopes.
+
+    Expects the endpoint to return a JSON array of envelope objects at
+    ``GET {base_url}/sessions/{session_id}/events?after={last_seq}``.
+    """
+
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        session_id: str,
+        participant_id: str,
+        poll_interval_ms: int = 1000,
+        auth_token: str | None = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._session_id = session_id
+        self._participant_id = participant_id
+        self._poll_interval = poll_interval_ms / 1000.0
+        self._auth_token = auth_token
+        self._stopped = False
+        self._last_seq = -1
+
+    def start(self) -> Iterator[IncomingMessage]:
+        """Poll the HTTP endpoint and yield messages."""
+        import urllib.request
+
+        url = f"{self._base_url}/sessions/{self._session_id}/events"
+        headers: dict[str, str] = {"Accept": "application/json"}
+        if self._auth_token:
+            headers["Authorization"] = f"Bearer {self._auth_token}"
+
+        while not self._stopped:
+            try:
+                req_url = f"{url}?after={self._last_seq}"
+                req = urllib.request.Request(req_url, headers=headers)
+                with urllib.request.urlopen(req, timeout=10) as resp:
+                    data = json.loads(resp.read().decode())
+
+                if isinstance(data, list):
+                    for item in data:
+                        seq = item.get("seq", self._last_seq + 1)
+                        if seq > self._last_seq:
+                            self._last_seq = seq
+                        yield IncomingMessage(
+                            message_type=item.get("message_type", ""),
+                            sender=item.get("sender", ""),
+                            payload=item.get("payload", {}),
+                            proposal_id=item.get("proposal_id"),
+                            seq=seq,
+                        )
+            except Exception:
+                logger.debug("http poll error, retrying in %ss", self._poll_interval)
+
+            if not self._stopped:
+                time.sleep(self._poll_interval)
+
+    def stop(self) -> None:
+        self._stopped = True
+
+
+def _envelope_to_message(envelope: Any) -> IncomingMessage:
+    """Convert a protobuf Envelope to an IncomingMessage."""
+    payload_dict: dict[str, Any] = {}
+    if envelope.payload:
+        try:
+            payload_dict = json.loads(envelope.payload)
+        except (json.JSONDecodeError, UnicodeDecodeError):
+            payload_dict = {"_raw_bytes": envelope.payload}
+
+    proposal_id: str | None = None
+    if "proposal_id" in payload_dict:
+        proposal_id = str(payload_dict["proposal_id"])
+
+    return IncomingMessage(
+        message_type=envelope.message_type,
+        sender=envelope.sender,
+        payload=payload_dict,
+        proposal_id=proposal_id,
+        raw=envelope,
+    )

macp_sdk/agent/types.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class IncomingMessage:
+    """A message received from the MACP session event stream."""
+
+    message_type: str
+    sender: str
+    payload: dict[str, Any]
+    proposal_id: str | None = None
+    raw: Any = None
+    seq: int | None = None
+
+
+@dataclass(slots=True)
+class SessionInfo:
+    """Metadata about the current MACP session."""
+
+    session_id: str
+    mode: str
+    participants: list[str] = field(default_factory=list)
+    mode_version: str | None = None
+    configuration_version: str | None = None
+    policy_version: str | None = None
+
+
+@dataclass(slots=True)
+class TerminalResult:
+    """Represents a terminal (committed/cancelled) session outcome."""
+
+    state: str
+    commitment: Any | None = None
+
+
+class HandlerContext:
+    """Context object passed to message handlers.
+
+    Provides access to participant identity, session state projection,
+    action methods, session metadata, and logging.
+    """
+
+    def __init__(
+        self,
+        participant: str,
+        projection: Any,
+        actions: Any,
+        session: SessionInfo,
+        log_fn: Callable[..., None],
+    ) -> None:
+        self.participant = participant
+        self.projection = projection
+        self.actions = actions
+        self.session = session
+        self.log = log_fn
+
+
+MessageHandler = Callable[[IncomingMessage, HandlerContext], None]
+TerminalHandler = Callable[[TerminalResult], None]
+PhaseChangeHandler = Callable[[str, HandlerContext], None]

macp_sdk/auth.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class AuthConfig:
+    """Authentication configuration for a MACP client or session.
+
+    The ``expected_sender`` field is a client-side guardrail: when set, any
+    explicit ``sender=`` passed to a session helper must match it, otherwise
+    the SDK raises :class:`MacpIdentityMismatchError` before the envelope
+    reaches the wire. Per RFC-MACP-0004 §4 the runtime derives ``sender``
+    from authenticated identity, so mismatches are always rejected — this
+    check just surfaces the problem earlier and more clearly.
+
+    When ``expected_sender`` is ``None`` the check is skipped (preserves
+    legacy behaviour for dev/test flows that use a single shared identity).
+    """
+
+    bearer_token: str | None = None
+    agent_id: str | None = None
+    sender_hint: str | None = None
+    expected_sender: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.bearer_token and self.agent_id:
+            raise ValueError("choose either bearer_token or agent_id, not both")
+        if not self.bearer_token and not self.agent_id:
+            raise ValueError("either bearer_token or agent_id is required")
+
+    @classmethod
+    def for_dev_agent(cls, agent_id: str, *, expected_sender: str | None = None) -> AuthConfig:
+        return cls(
+            agent_id=agent_id,
+            sender_hint=agent_id,
+            expected_sender=expected_sender or agent_id,
+        )
+
+    @classmethod
+    def for_bearer(
+        cls,
+        token: str,
+        *,
+        sender_hint: str | None = None,
+        expected_sender: str | None = None,
+    ) -> AuthConfig:
+        """Build a Bearer-token AuthConfig.
+
+        :param token: the Bearer token issued by the runtime
+        :param sender_hint: the sender string the SDK places on envelopes when
+            no explicit ``sender=`` is provided. Defaults to ``expected_sender``
+            when only the latter is supplied.
+        :param expected_sender: the identity the runtime will bind this token
+            to. When set, the SDK rejects any explicit ``sender=`` that does
+            not match with :class:`MacpIdentityMismatchError`.
+        """
+        return cls(
+            bearer_token=token,
+            sender_hint=sender_hint or expected_sender,
+            expected_sender=expected_sender,
+        )
+
+    @property
+    def sender(self) -> str | None:
+        return self.sender_hint or self.agent_id
+
+    def metadata(self) -> list[tuple[str, str]]:
+        headers: list[tuple[str, str]] = []
+        if self.bearer_token:
+            headers.append(("authorization", f"Bearer {self.bearer_token}"))
+        if self.agent_id:
+            headers.append(("x-macp-agent-id", self.agent_id))
+        return headers

macp_sdk/base_projection.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import ClassVar
+
+from macp.v1 import core_pb2, envelope_pb2
+
+
+class BaseProjection(ABC):
+    """Abstract base for in-process mode state tracking.
+
+    Maintains a local transcript and delegates mode-specific message handling
+    to subclasses.  Needed because the runtime's ``GetSession`` RPC returns
+    metadata only, not mode state or transcript.
+    """
+
+    MODE: ClassVar[str]
+
+    def __init__(self) -> None:
+        self.transcript: list[envelope_pb2.Envelope] = []
+        self.phase: str = ""
+        self.commitment: core_pb2.CommitmentPayload | None = None
+
+    @property
+    def is_committed(self) -> bool:
+        return self.commitment is not None
+
+    @property
+    def is_positive_outcome(self) -> bool | None:
+        """Return the outcome polarity, or ``None`` if not yet committed."""
+        if self.commitment is None:
+            return None
+        return getattr(self.commitment, "outcome_positive", True)
+
+    def apply_envelope(self, envelope: envelope_pb2.Envelope) -> None:
+        """Process an accepted envelope and update local state."""
+        if envelope.mode != self.MODE:
+            return
+        self.transcript.append(envelope)
+
+        if envelope.message_type == "Commitment":
+            payload = core_pb2.CommitmentPayload()
+            payload.ParseFromString(envelope.payload)
+            self.commitment = payload
+            self.phase = "Committed"
+            return
+
+        self._apply_mode_message(envelope)
+
+    @abstractmethod
+    def _apply_mode_message(self, envelope: envelope_pb2.Envelope) -> None:
+        """Handle a mode-specific (non-Commitment) envelope."""