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

macp_sdk/proposal.py

@@ -0,0 +1,305 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from macp.modes.proposal.v1 import proposal_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_PROPOSAL
+from .envelope import build_envelope, serialize_message
+from .errors import MacpSessionError
+
+# ---------------------------------------------------------------------------
+# Projection records
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class ProposalRecord:
+    proposal_id: str
+    title: str
+    summary: str
+    proposer: str
+    supersedes: str  # "" if original
+    status: str  # "open" | "accepted" | "rejected" | "withdrawn"
+    tags: list[str]
+
+
+@dataclass(slots=True)
+class RejectRecord:
+    proposal_id: str
+    reason: str
+    sender: str
+    terminal: bool
+
+
+@dataclass(slots=True)
+class AcceptRecord:
+    proposal_id: str
+    reason: str
+    sender: str
+
+
+# ---------------------------------------------------------------------------
+# Projection
+# ---------------------------------------------------------------------------
+
+
+class ProposalProjection(BaseProjection):
+    """In-process state tracking for Proposal mode sessions."""
+
+    MODE = MODE_PROPOSAL
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.phase = "Negotiating"
+        self.proposals: dict[str, ProposalRecord] = {}
+        self.accepts: list[AcceptRecord] = []
+        self.rejections: list[RejectRecord] = []
+
+    def _apply_mode_message(self, envelope: envelope_pb2.Envelope) -> None:
+        mt = envelope.message_type
+
+        if mt == "Proposal":
+            p = proposal_pb2.ProposalPayload()
+            p.ParseFromString(envelope.payload)
+            self.proposals[p.proposal_id] = ProposalRecord(
+                proposal_id=p.proposal_id,
+                title=p.title,
+                summary=p.summary,
+                proposer=envelope.sender,
+                supersedes="",
+                status="open",
+                tags=list(p.tags),
+            )
+            return
+
+        if mt == "CounterProposal":
+            p = proposal_pb2.CounterProposalPayload()
+            p.ParseFromString(envelope.payload)
+            self.proposals[p.proposal_id] = ProposalRecord(
+                proposal_id=p.proposal_id,
+                title=p.title,
+                summary=p.summary,
+                proposer=envelope.sender,
+                supersedes=p.supersedes_proposal_id,
+                status="open",
+                tags=[],
+            )
+            return
+
+        if mt == "Accept":
+            p = proposal_pb2.AcceptPayload()
+            p.ParseFromString(envelope.payload)
+            self.accepts.append(
+                AcceptRecord(
+                    proposal_id=p.proposal_id,
+                    reason=p.reason,
+                    sender=envelope.sender,
+                )
+            )
+            return
+
+        if mt == "Reject":
+            p = proposal_pb2.RejectPayload()
+            p.ParseFromString(envelope.payload)
+            self.rejections.append(
+                RejectRecord(
+                    proposal_id=p.proposal_id,
+                    reason=p.reason,
+                    sender=envelope.sender,
+                    terminal=p.terminal,
+                )
+            )
+            if p.terminal:
+                rec = self.proposals.get(p.proposal_id)
+                if rec is not None:
+                    rec.status = "rejected"
+                self.phase = "TerminalRejected"
+            return
+
+        if mt == "Withdraw":
+            p = proposal_pb2.WithdrawPayload()
+            p.ParseFromString(envelope.payload)
+            rec = self.proposals.get(p.proposal_id)
+            if rec is not None:
+                rec.status = "withdrawn"
+
+    # -- State query helpers --
+
+    def live_proposals(self) -> dict[str, ProposalRecord]:
+        """Return proposals that have not been withdrawn."""
+        return {k: v for k, v in self.proposals.items() if v.status != "withdrawn"}
+
+    def accepted_proposal(self) -> str | None:
+        """Return the proposal_id that all accepting senders agree on, or None."""
+        if not self.accepts:
+            return None
+        ids = {a.proposal_id for a in self.accepts}
+        if len(ids) == 1:
+            return ids.pop()
+        return None
+
+    def has_terminal_rejection(self) -> bool:
+        return any(r.terminal for r in self.rejections)
+
+    def active_proposals(self) -> list[ProposalRecord]:
+        """Return proposals whose status is 'open'."""
+        return [p for p in self.proposals.values() if p.status == "open"]
+
+    def latest_proposal(self) -> ProposalRecord | None:
+        """Return the most recently added proposal, or None."""
+        if not self.proposals:
+            return None
+        return list(self.proposals.values())[-1]
+
+    def is_accepted(self, proposal_id: str) -> bool:
+        """True if any accept record references *proposal_id*."""
+        return any(a.proposal_id == proposal_id for a in self.accepts)
+
+    def is_terminally_rejected(self, proposal_id: str) -> bool:
+        """True if a terminal rejection exists for *proposal_id*."""
+        return any(r.proposal_id == proposal_id and r.terminal for r in self.rejections)
+
+
+# ---------------------------------------------------------------------------
+# Session helper
+# ---------------------------------------------------------------------------
+
+
+class ProposalSession(BaseSession):
+    """High-level helper for Proposal mode sessions."""
+
+    MODE = MODE_PROPOSAL
+
+    def _create_projection(self) -> BaseProjection:
+        return ProposalProjection()
+
+    @property
+    def proposal_projection(self) -> ProposalProjection:
+        assert isinstance(self.projection, ProposalProjection)
+        return self.projection
+
+    def propose(
+        self,
+        proposal_id: str,
+        title: str,
+        *,
+        summary: str = "",
+        details: bytes = b"",
+        tags: list[str] | None = None,
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        payload = proposal_pb2.ProposalPayload(
+            proposal_id=proposal_id,
+            title=title,
+            summary=summary,
+            details=details,
+            tags=tags or [],
+        )
+        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 counter_propose(
+        self,
+        proposal_id: str,
+        supersedes_proposal_id: str,
+        title: str,
+        *,
+        summary: str = "",
+        details: bytes = b"",
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        payload = proposal_pb2.CounterProposalPayload(
+            proposal_id=proposal_id,
+            supersedes_proposal_id=supersedes_proposal_id,
+            title=title,
+            summary=summary,
+            details=details,
+        )
+        envelope = build_envelope(
+            mode=self.MODE,
+            message_type="CounterProposal",
+            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(
+        self,
+        proposal_id: str,
+        *,
+        reason: str = "",
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        payload = proposal_pb2.AcceptPayload(
+            proposal_id=proposal_id,
+            reason=reason,
+        )
+        envelope = build_envelope(
+            mode=self.MODE,
+            message_type="Accept",
+            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 reject(
+        self,
+        proposal_id: str,
+        *,
+        terminal: bool = False,
+        reason: str = "",
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        payload = proposal_pb2.RejectPayload(
+            proposal_id=proposal_id,
+            terminal=terminal,
+            reason=reason,
+        )
+        envelope = build_envelope(
+            mode=self.MODE,
+            message_type="Reject",
+            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 withdraw(
+        self,
+        proposal_id: str,
+        *,
+        reason: str = "",
+        sender: str | None = None,
+        auth: AuthConfig | None = None,
+    ) -> envelope_pb2.Ack:
+        if not proposal_id or not proposal_id.strip():
+            raise MacpSessionError("proposal_id must be non-empty for withdraw")
+        payload = proposal_pb2.WithdrawPayload(
+            proposal_id=proposal_id,
+            reason=reason,
+        )
+        envelope = build_envelope(
+            mode=self.MODE,
+            message_type="Withdraw",
+            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/proto_registry.py

@@ -0,0 +1,150 @@
+"""Centralized protobuf encode/decode registry for MACP message types.
+
+Uses compiled ``_pb2`` modules (via ``google.protobuf.symbol_database``) to
+look up message classes by fully-qualified type name.
+"""
+
+from __future__ import annotations
+
+import base64
+import importlib
+import json
+from typing import Any
+
+from google.protobuf import json_format, symbol_database  # type: ignore[import-untyped]
+
+from .constants import (
+    MODE_DECISION,
+    MODE_HANDOFF,
+    MODE_MULTI_ROUND,
+    MODE_PROPOSAL,
+    MODE_QUORUM,
+    MODE_TASK,
+)
+
+# ── Type-name mappings (mirrors TypeScript CORE_MAP / MODE_MAP) ──────
+
+CORE_MAP: dict[str, str] = {
+    "SessionStart": "macp.v1.SessionStartPayload",
+    "Commitment": "macp.v1.CommitmentPayload",
+    "Signal": "macp.v1.SignalPayload",
+    "Progress": "macp.v1.ProgressPayload",
+}
+
+MODE_MAP: dict[str, dict[str, str]] = {
+    MODE_DECISION: {
+        "Proposal": "macp.modes.decision.v1.ProposalPayload",
+        "Evaluation": "macp.modes.decision.v1.EvaluationPayload",
+        "Objection": "macp.modes.decision.v1.ObjectionPayload",
+        "Vote": "macp.modes.decision.v1.VotePayload",
+    },
+    MODE_PROPOSAL: {
+        "Proposal": "macp.modes.proposal.v1.ProposalPayload",
+        "CounterProposal": "macp.modes.proposal.v1.CounterProposalPayload",
+        "Accept": "macp.modes.proposal.v1.AcceptPayload",
+        "Reject": "macp.modes.proposal.v1.RejectPayload",
+        "Withdraw": "macp.modes.proposal.v1.WithdrawPayload",
+    },
+    MODE_TASK: {
+        "TaskRequest": "macp.modes.task.v1.TaskRequestPayload",
+        "TaskAccept": "macp.modes.task.v1.TaskAcceptPayload",
+        "TaskReject": "macp.modes.task.v1.TaskRejectPayload",
+        "TaskUpdate": "macp.modes.task.v1.TaskUpdatePayload",
+        "TaskComplete": "macp.modes.task.v1.TaskCompletePayload",
+        "TaskFail": "macp.modes.task.v1.TaskFailPayload",
+    },
+    MODE_HANDOFF: {
+        "HandoffOffer": "macp.modes.handoff.v1.HandoffOfferPayload",
+        "HandoffContext": "macp.modes.handoff.v1.HandoffContextPayload",
+        "HandoffAccept": "macp.modes.handoff.v1.HandoffAcceptPayload",
+        "HandoffDecline": "macp.modes.handoff.v1.HandoffDeclinePayload",
+    },
+    MODE_QUORUM: {
+        "ApprovalRequest": "macp.modes.quorum.v1.ApprovalRequestPayload",
+        "Approve": "macp.modes.quorum.v1.ApprovePayload",
+        "Reject": "macp.modes.quorum.v1.RejectPayload",
+        "Abstain": "macp.modes.quorum.v1.AbstainPayload",
+    },
+    MODE_MULTI_ROUND: {
+        "Contribute": "__json__",
+    },
+}
+
+# Ensure all _pb2 modules are imported so descriptors are registered.
+_PB2_MODULES_LOADED = False
+
+
+def _ensure_pb2_imports() -> None:
+    global _PB2_MODULES_LOADED
+    if _PB2_MODULES_LOADED:
+        return
+    # Import all proto modules to register their descriptors in the global pool.
+    for _mod in (
+        "macp.v1.core_pb2",
+        "macp.v1.envelope_pb2",
+        "macp.v1.policy_pb2",
+        "macp.modes.decision.v1.decision_pb2",
+        "macp.modes.proposal.v1.proposal_pb2",
+        "macp.modes.task.v1.task_pb2",
+        "macp.modes.handoff.v1.handoff_pb2",
+        "macp.modes.quorum.v1.quorum_pb2",
+    ):
+        importlib.import_module(_mod)
+    _PB2_MODULES_LOADED = True
+
+
+class ProtoRegistry:
+    """Registry for protobuf type-name-based encode/decode of MACP payloads."""
+
+    def __init__(self) -> None:
+        _ensure_pb2_imports()
+        self._db = symbol_database.Default()
+
+    def get_known_type_name(self, mode: str, message_type: str) -> str | None:
+        """Return the fully-qualified protobuf type name, or None if unknown."""
+        return MODE_MAP.get(mode, {}).get(message_type) or CORE_MAP.get(message_type)
+
+    def encode_message(self, type_name: str, value: dict[str, Any]) -> bytes:
+        """Encode *value* as a protobuf message identified by *type_name*."""
+        cls = self._db.GetSymbol(type_name)
+        msg = json_format.ParseDict(value, cls())
+        return msg.SerializeToString()
+
+    def decode_message(self, type_name: str, payload: bytes) -> dict[str, Any]:
+        """Decode *payload* into a dict using the message class for *type_name*."""
+        cls = self._db.GetSymbol(type_name)
+        msg = cls()
+        msg.ParseFromString(payload)
+        return json_format.MessageToDict(msg, preserving_proto_field_name=True)
+
+    def encode_known_payload(self, mode: str, message_type: str, value: dict[str, Any]) -> bytes:
+        """Encode *value* using the known type mapping for *mode*/*message_type*."""
+        type_name = self.get_known_type_name(mode, message_type)
+        if type_name is None:
+            raise ValueError(f"unknown payload mapping for {mode}/{message_type}")
+        if type_name == "__json__":
+            return json.dumps(value).encode("utf-8")
+        return self.encode_message(type_name, value)
+
+    def decode_known_payload(
+        self, mode: str, message_type: str, payload: bytes
+    ) -> dict[str, Any] | None:
+        """Decode *payload* using the known type mapping, or try UTF-8 fallback."""
+        type_name = self.get_known_type_name(mode, message_type)
+        if type_name is None or type_name == "__json__":
+            return self._try_decode_utf8(payload)
+        return self.decode_message(type_name, payload)
+
+    @staticmethod
+    def _try_decode_utf8(payload: bytes) -> dict[str, Any] | None:
+        if not payload:
+            return None
+        text = payload.decode("utf-8")
+        try:
+            return {"encoding": "json", "json": json.loads(text)}
+        except (json.JSONDecodeError, ValueError):
+            return {
+                "encoding": "text",
+                "text": text,
+                "payload_base64": base64.b64encode(payload).decode(),
+            }