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

macp_sdk/decision.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from macp.modes.decision.v1 import decision_pb2
+from macp.v1 import envelope_pb2
+
+from .auth import AuthConfig
+from .base_projection import BaseProjection
+from .base_session import BaseSession
+from .constants import MODE_DECISION
+from .envelope import build_envelope, serialize_message
+from .errors import MacpSessionError
+from .projections import DecisionProjection
+
+_VALID_VOTES = frozenset({"APPROVE", "REJECT", "ABSTAIN"})
+_VALID_RECOMMENDATIONS = frozenset({"APPROVE", "REVIEW", "BLOCK", "REJECT"})
+_VALID_SEVERITIES = frozenset({"critical", "high", "medium", "low"})
+
+
+class DecisionSession(BaseSession):
+    """High-level helper for Decision mode sessions.
+
+    Inherits ``start``, ``commit``, ``cancel``, ``metadata``, and ``open_stream``
+    from :class:`BaseSession`.  Adds decision-specific actions: ``propose``,
+    ``evaluate``, ``raise_objection``, and ``vote``.
+
+    Note: The initiator must be included in the ``participants`` list passed
+    to ``start()`` in order to propose.  The runtime no longer grants
+    implicit proposal authority to the initiator.
+    """
+
+    MODE = MODE_DECISION
+
+    def _create_projection(self) -> BaseProjection:
+        return DecisionProjection()
+
+    # Narrow the type for callers that want decision-specific queries.
+    @property
+    def decision_projection(self) -> DecisionProjection:
+        assert isinstance(self.projection, DecisionProjection)
+        return self.projection
+
+    def propose(
+        self,
+        proposal_id: str,
+        option: str,
+        *,
+        rationale: str = "",
+        supporting_data: bytes = b"",
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        payload = decision_pb2.ProposalPayload(
+            proposal_id=proposal_id,
+            option=option,
+            rationale=rationale,
+            supporting_data=supporting_data,
+        )
+        envelope = build_envelope(
+            mode=self.MODE,
+            message_type="Proposal",
+            session_id=self.session_id,
+            sender=self._sender_for(sender, auth=auth),
+            payload=serialize_message(payload),
+        )
+        return self._send_and_track(envelope, auth=auth)
+
+    def evaluate(
+        self,
+        proposal_id: str,
+        recommendation: str,
+        *,
+        confidence: float,
+        reason: str = "",
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        normalized_rec = recommendation.upper()
+        if normalized_rec not in _VALID_RECOMMENDATIONS:
+            raise MacpSessionError(
+                f"invalid recommendation {recommendation!r}: "
+                "must be one of APPROVE, REVIEW, BLOCK, REJECT"
+            )
+        if not (0.0 <= confidence <= 1.0):
+            raise MacpSessionError(f"confidence must be in [0.0, 1.0], got {confidence}")
+        payload = decision_pb2.EvaluationPayload(
+            proposal_id=proposal_id,
+            recommendation=normalized_rec,
+            confidence=confidence,
+            reason=reason,
+        )
+        envelope = build_envelope(
+            mode=self.MODE,
+            message_type="Evaluation",
+            session_id=self.session_id,
+            sender=self._sender_for(sender, auth=auth),
+            payload=serialize_message(payload),
+        )
+        return self._send_and_track(envelope, auth=auth)
+
+    def raise_objection(
+        self,
+        proposal_id: str,
+        *,
+        reason: str,
+        severity: str = "medium",
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        normalized_sev = severity.lower()
+        if normalized_sev not in _VALID_SEVERITIES:
+            raise MacpSessionError(
+                f"invalid severity {severity!r}: must be one of critical, high, medium, low"
+            )
+        payload = decision_pb2.ObjectionPayload(
+            proposal_id=proposal_id,
+            reason=reason,
+            severity=normalized_sev,
+        )
+        envelope = build_envelope(
+            mode=self.MODE,
+            message_type="Objection",
+            session_id=self.session_id,
+            sender=self._sender_for(sender, auth=auth),
+            payload=serialize_message(payload),
+        )
+        return self._send_and_track(envelope, auth=auth)
+
+    def vote(
+        self,
+        proposal_id: str,
+        vote: str,
+        *,
+        reason: str = "",
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        normalized_vote = vote.upper()
+        if normalized_vote not in _VALID_VOTES:
+            raise MacpSessionError(
+                f"invalid vote value {vote!r}: must be one of APPROVE, REJECT, ABSTAIN"
+            )
+        payload = decision_pb2.VotePayload(
+            proposal_id=proposal_id,
+            vote=normalized_vote,
+            reason=reason,
+        )
+        envelope = build_envelope(
+            mode=self.MODE,
+            message_type="Vote",
+            session_id=self.session_id,
+            sender=self._sender_for(sender, auth=auth),
+            payload=serialize_message(payload),
+        )
+        return self._send_and_track(envelope, auth=auth)

macp_sdk/envelope.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from collections.abc import Iterable, Mapping, Sequence
+
+from macp.v1 import core_pb2, envelope_pb2
+
+from .constants import (
+    DEFAULT_CONFIGURATION_VERSION,
+    DEFAULT_MODE_VERSION,
+    DEFAULT_POLICY_VERSION,
+    MACP_VERSION,
+)
+from .errors import MacpSessionError
+
+# ── Outcome inference ────────────────────────────────────────────────
+
+_NEGATIVE_SUFFIXES = ("rejected", "failed", "declined")
+_POSITIVE_SUFFIXES = ("selected", "accepted", "completed", "approved")
+
+
+def infer_outcome_positive(action: str) -> bool:
+    """Infer ``outcome_positive`` from the action suffix.
+
+    Actions ending in *rejected*, *failed*, or *declined* are negative.
+    Everything else (including unknown suffixes) defaults to positive.
+    """
+    lower = action.lower()
+    return not any(lower.endswith(s) for s in _NEGATIVE_SUFFIXES)
+
+
+def new_session_id() -> str:
+    return str(uuid.uuid4())
+
+
+def new_message_id() -> str:
+    return str(uuid.uuid4())
+
+
+def new_commitment_id() -> str:
+    return str(uuid.uuid4())
+
+
+def now_unix_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def encode_context(context: bytes | str | Mapping[str, object] | None) -> bytes:
+    if context is None:
+        return b""
+    if isinstance(context, bytes):
+        return context
+    if isinstance(context, str):
+        return context.encode("utf-8")
+    return json.dumps(context).encode("utf-8")
+
+
+def build_root(uri: str, name: str = "") -> core_pb2.Root:
+    return core_pb2.Root(uri=uri, name=name)
+
+
+def build_session_start_payload(
+    *,
+    intent: str,
+    participants: Sequence[str],
+    ttl_ms: int,
+    mode_version: str = DEFAULT_MODE_VERSION,
+    configuration_version: str = DEFAULT_CONFIGURATION_VERSION,
+    policy_version: str = DEFAULT_POLICY_VERSION,
+    context: bytes | str | Mapping[str, object] | None = None,
+    roots: Iterable[core_pb2.Root] | None = None,
+) -> core_pb2.SessionStartPayload:
+    return core_pb2.SessionStartPayload(
+        intent=intent,
+        participants=list(participants),
+        mode_version=mode_version,
+        configuration_version=configuration_version,
+        policy_version=policy_version,
+        ttl_ms=ttl_ms,
+        context=encode_context(context),
+        roots=list(roots or []),
+    )
+
+
+def _has_outcome_positive_field() -> bool:
+    """Check if the proto schema supports outcome_positive."""
+    return any(f.name == "outcome_positive" for f in core_pb2.CommitmentPayload.DESCRIPTOR.fields)
+
+
+def build_commitment_payload(
+    *,
+    action: str,
+    authority_scope: str,
+    reason: str,
+    commitment_id: str | None = None,
+    mode_version: str = DEFAULT_MODE_VERSION,
+    configuration_version: str = DEFAULT_CONFIGURATION_VERSION,
+    policy_version: str = DEFAULT_POLICY_VERSION,
+    outcome_positive: bool | None = None,
+) -> core_pb2.CommitmentPayload:
+    if outcome_positive is None:
+        outcome_positive = infer_outcome_positive(action)
+    kwargs: dict[str, object] = dict(
+        commitment_id=commitment_id or new_commitment_id(),
+        action=action,
+        authority_scope=authority_scope,
+        reason=reason,
+        mode_version=mode_version,
+        configuration_version=configuration_version,
+        policy_version=policy_version,
+    )
+    if _has_outcome_positive_field():
+        kwargs["outcome_positive"] = outcome_positive
+    return core_pb2.CommitmentPayload(**kwargs)
+
+
+def build_signal_payload(
+    *,
+    signal_type: str,
+    data: bytes = b"",
+    confidence: float = 0.0,
+    correlation_session_id: str = "",
+) -> core_pb2.SignalPayload:
+    if data and not signal_type.strip():
+        raise MacpSessionError("signal_type must be non-empty when data is present")
+    return core_pb2.SignalPayload(
+        signal_type=signal_type,
+        data=data,
+        confidence=confidence,
+        correlation_session_id=correlation_session_id,
+    )
+
+
+def build_progress_payload(
+    *,
+    progress_token: str,
+    progress: float,
+    total: float,
+    message: str = "",
+    target_message_id: str = "",
+) -> core_pb2.ProgressPayload:
+    return core_pb2.ProgressPayload(
+        progress_token=progress_token,
+        progress=progress,
+        total=total,
+        message=message,
+        target_message_id=target_message_id,
+    )
+
+
+def serialize_message(message: object) -> bytes:
+    serializer = getattr(message, "SerializeToString", None)
+    if serializer is None:
+        raise TypeError(f"object {type(message)!r} is not a protobuf message")
+    return serializer()
+
+
+def build_envelope(
+    *,
+    mode: str,
+    message_type: str,
+    session_id: str,
+    payload: bytes,
+    sender: str = "",
+    message_id: str | None = None,
+    macp_version: str = MACP_VERSION,
+    timestamp_unix_ms: int | None = None,
+) -> envelope_pb2.Envelope:
+    return envelope_pb2.Envelope(
+        macp_version=macp_version,
+        mode=mode,
+        message_type=message_type,
+        message_id=message_id or new_message_id(),
+        session_id=session_id,
+        sender=sender,
+        timestamp_unix_ms=timestamp_unix_ms or now_unix_ms(),
+        payload=payload,
+    )

macp_sdk/errors.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# ── Well-known error codes ───────────────────────────────────────────
+
+SESSION_ALREADY_EXISTS = "SESSION_ALREADY_EXISTS"
+POLICY_DENIED = "POLICY_DENIED"
+UNKNOWN_POLICY_VERSION = "UNKNOWN_POLICY_VERSION"
+INVALID_POLICY_DEFINITION = "INVALID_POLICY_DEFINITION"
+UNSUPPORTED_PROTOCOL_VERSION = "UNSUPPORTED_PROTOCOL_VERSION"
+INVALID_ENVELOPE = "INVALID_ENVELOPE"
+SESSION_NOT_FOUND = "SESSION_NOT_FOUND"
+SESSION_NOT_OPEN = "SESSION_NOT_OPEN"
+MODE_NOT_SUPPORTED = "MODE_NOT_SUPPORTED"
+FORBIDDEN = "FORBIDDEN"
+UNAUTHENTICATED = "UNAUTHENTICATED"
+DUPLICATE_MESSAGE = "DUPLICATE_MESSAGE"
+PAYLOAD_TOO_LARGE = "PAYLOAD_TOO_LARGE"
+RATE_LIMITED = "RATE_LIMITED"
+INTERNAL_ERROR = "INTERNAL_ERROR"
+INVALID_SESSION_ID = "INVALID_SESSION_ID"
+
+
+class MacpSdkError(Exception):
+    """Base SDK exception."""
+
+
+@dataclass(slots=True)
+class AckFailure:
+    code: str
+    message: str
+    session_id: str = ""
+    message_id: str = ""
+    reasons: list[str] = field(default_factory=list)
+
+
+class MacpAckError(MacpSdkError):
+    """Runtime rejected the message (NACK)."""
+
+    def __init__(
+        self,
+        failure: AckFailure,
+        *,
+        mode: str = "",
+        message_type: str = "",
+    ):
+        self.failure = failure
+        self.mode = mode
+        self.message_type = message_type
+        super().__init__(f"{failure.code}: {failure.message}")
+
+    @property
+    def reasons(self) -> list[str]:
+        """Structured denial reasons (populated for POLICY_DENIED)."""
+        return self.failure.reasons
+
+    def __repr__(self) -> str:
+        parts = [f"code={self.failure.code!r}", f"message={self.failure.message!r}"]
+        if self.failure.session_id:
+            parts.append(f"session_id={self.failure.session_id!r}")
+        if self.mode:
+            parts.append(f"mode={self.mode!r}")
+        if self.message_type:
+            parts.append(f"message_type={self.message_type!r}")
+        if self.failure.reasons:
+            parts.append(f"reasons={self.failure.reasons!r}")
+        return f"MacpAckError({', '.join(parts)})"
+
+
+class MacpTransportError(MacpSdkError):
+    """gRPC communication failure."""
+
+
+class MacpSessionError(MacpSdkError):
+    """Session-level error (wrong state, not started, already committed)."""
+
+
+class MacpIdentityMismatchError(MacpSdkError):
+    """Envelope ``sender`` does not match the auth identity's ``expected_sender``.
+
+    The runtime derives ``sender`` from authenticated identity and rejects any
+    value that does not match (RFC-MACP-0004 §4). Catching this mismatch client-side
+    surfaces a clearer error than an opaque ``UNAUTHENTICATED`` from the runtime.
+    """
+
+    def __init__(self, *, expected: str, actual: str) -> None:
+        self.expected = expected
+        self.actual = actual
+        super().__init__(
+            f"sender {actual!r} does not match auth identity {expected!r}; "
+            f"the runtime will reject this envelope as UNAUTHENTICATED"
+        )
+
+
+class MacpTimeoutError(MacpTransportError):
+    """Operation timed out."""
+
+
+class MacpRetryError(MacpTransportError):
+    """All retry attempts exhausted."""

macp_sdk/handoff.py

@@ -0,0 +1,241 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from macp.modes.handoff.v1 import handoff_pb2
+from macp.v1 import envelope_pb2
+
+from .auth import AuthConfig
+from .base_projection import BaseProjection
+from .base_session import BaseSession
+from .constants import MODE_HANDOFF
+from .envelope import build_envelope, serialize_message
+
+# ---------------------------------------------------------------------------
+# Projection records
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class HandoffRecord:
+    handoff_id: str
+    target_participant: str
+    scope: str
+    reason: str
+    sender: str
+    status: str  # "offered" | "context_sent" | "accepted" | "declined"
+    context_content_type: str | None
+    accepted_by: str | None
+    declined_by: str | None
+
+
+# ---------------------------------------------------------------------------
+# Projection
+# ---------------------------------------------------------------------------
+
+
+class HandoffProjection(BaseProjection):
+    """In-process state tracking for Handoff mode sessions."""
+
+    MODE = MODE_HANDOFF
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.phase = "Pending"
+        self.handoffs: dict[str, HandoffRecord] = {}
+
+    def _apply_mode_message(self, envelope: envelope_pb2.Envelope) -> None:
+        mt = envelope.message_type
+
+        if mt == "HandoffOffer":
+            p = handoff_pb2.HandoffOfferPayload()
+            p.ParseFromString(envelope.payload)
+            self.handoffs[p.handoff_id] = HandoffRecord(
+                handoff_id=p.handoff_id,
+                target_participant=p.target_participant,
+                scope=p.scope,
+                reason=p.reason,
+                sender=envelope.sender,
+                status="offered",
+                context_content_type=None,
+                accepted_by=None,
+                declined_by=None,
+            )
+            self.phase = "OfferPending"
+            return
+
+        if mt == "HandoffContext":
+            p = handoff_pb2.HandoffContextPayload()
+            p.ParseFromString(envelope.payload)
+            handoff = self.handoffs.get(p.handoff_id)
+            if handoff is not None:
+                if handoff.status == "offered":
+                    handoff.status = "context_sent"
+                handoff.context_content_type = p.content_type
+            if self.phase == "OfferPending":
+                self.phase = "ContextSharing"
+            return
+
+        if mt == "HandoffAccept":
+            p = handoff_pb2.HandoffAcceptPayload()
+            p.ParseFromString(envelope.payload)
+            handoff = self.handoffs.get(p.handoff_id)
+            if handoff is not None:
+                handoff.status = "accepted"
+                handoff.accepted_by = p.accepted_by
+            self.phase = "Accepted"
+            return
+
+        if mt == "HandoffDecline":
+            p = handoff_pb2.HandoffDeclinePayload()
+            p.ParseFromString(envelope.payload)
+            handoff = self.handoffs.get(p.handoff_id)
+            if handoff is not None:
+                handoff.status = "declined"
+                handoff.declined_by = p.declined_by
+            self.phase = "Declined"
+
+    # -- State query helpers --
+
+    def has_accepted_offer(self, handoff_id: str | None = None) -> bool:
+        """True if any offer (or a specific one) has been accepted."""
+        if handoff_id is not None:
+            handoff = self.handoffs.get(handoff_id)
+            return handoff is not None and handoff.status == "accepted"
+        return any(h.status == "accepted" for h in self.handoffs.values())
+
+    def active_offer(self) -> HandoffRecord | None:
+        """Return the most recent pending offer, or None."""
+        for handoff in reversed(list(self.handoffs.values())):
+            if handoff.status in ("offered", "context_sent"):
+                return handoff
+        return None
+
+    def is_accepted(self, handoff_id: str) -> bool:
+        handoff = self.handoffs.get(handoff_id)
+        return handoff is not None and handoff.status == "accepted"
+
+    def is_declined(self, handoff_id: str) -> bool:
+        handoff = self.handoffs.get(handoff_id)
+        return handoff is not None and handoff.status == "declined"
+
+    def get_handoff(self, handoff_id: str) -> HandoffRecord | None:
+        """Return the handoff record for *handoff_id*, or None."""
+        return self.handoffs.get(handoff_id)
+
+    def pending_handoffs(self) -> list[HandoffRecord]:
+        """Return handoffs that are still pending (offered or context_sent)."""
+        return [h for h in self.handoffs.values() if h.status in ("offered", "context_sent")]
+
+
+# ---------------------------------------------------------------------------
+# Session helper
+# ---------------------------------------------------------------------------
+
+
+class HandoffSession(BaseSession):
+    """High-level helper for Handoff mode sessions."""
+
+    MODE = MODE_HANDOFF
+
+    def _create_projection(self) -> BaseProjection:
+        return HandoffProjection()
+
+    @property
+    def handoff_projection(self) -> HandoffProjection:
+        assert isinstance(self.projection, HandoffProjection)
+        return self.projection
+
+    def offer(
+        self,
+        handoff_id: str,
+        target_participant: str,
+        *,
+        scope: str = "",
+        reason: str = "",
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        payload = handoff_pb2.HandoffOfferPayload(
+            handoff_id=handoff_id,
+            target_participant=target_participant,
+            scope=scope,
+            reason=reason,
+        )
+        envelope = build_envelope(
+            mode=self.MODE,
+            message_type="HandoffOffer",
+            session_id=self.session_id,
+            sender=self._sender_for(sender, auth=auth),
+            payload=serialize_message(payload),
+        )
+        return self._send_and_track(envelope, auth=auth)
+
+    def add_context(
+        self,
+        handoff_id: str,
+        *,
+        content_type: str = "application/octet-stream",
+        context: bytes = b"",
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        payload = handoff_pb2.HandoffContextPayload(
+            handoff_id=handoff_id,
+            content_type=content_type,
+            context=context,
+        )
+        envelope = build_envelope(
+            mode=self.MODE,
+            message_type="HandoffContext",
+            session_id=self.session_id,
+            sender=self._sender_for(sender, auth=auth),
+            payload=serialize_message(payload),
+        )
+        return self._send_and_track(envelope, auth=auth)
+
+    def accept_handoff(
+        self,
+        handoff_id: str,
+        *,
+        accepted_by: str = "",
+        reason: str = "",
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        payload = handoff_pb2.HandoffAcceptPayload(
+            handoff_id=handoff_id,
+            accepted_by=accepted_by or self._sender_for(sender, auth=auth),
+            reason=reason,
+        )
+        envelope = build_envelope(
+            mode=self.MODE,
+            message_type="HandoffAccept",
+            session_id=self.session_id,
+            sender=self._sender_for(sender, auth=auth),
+            payload=serialize_message(payload),
+        )
+        return self._send_and_track(envelope, auth=auth)
+
+    def decline(
+        self,
+        handoff_id: str,
+        *,
+        declined_by: str = "",
+        reason: str = "",
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        payload = handoff_pb2.HandoffDeclinePayload(
+            handoff_id=handoff_id,
+            declined_by=declined_by or self._sender_for(sender, auth=auth),
+            reason=reason,
+        )
+        envelope = build_envelope(
+            mode=self.MODE,
+            message_type="HandoffDecline",
+            session_id=self.session_id,
+            sender=self._sender_for(sender, auth=auth),
+            payload=serialize_message(payload),
+        )
+        return self._send_and_track(envelope, auth=auth)