macp-sdk-python 0.10.2__tar.gz → 0.12.1__tar.gz

{macp_sdk_python-0.10.2 → macp_sdk_python-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: macp-sdk-python
-Version: 0.10.2
+Version: 0.12.1
 Summary: Python SDK for the MACP Rust runtime
 Author-email: Multi-Agent Coordination Protocol <macp@multiagentcoordinationprotocol.org>
 License: Apache-2.0

{macp_sdk_python-0.10.2 → macp_sdk_python-0.12.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "macp-sdk-python"
-version = "0.10.2"
+version = "0.12.1"
 description = "Python SDK for the MACP Rust runtime"
 readme = "README.md"
 requires-python = ">=3.11"

{macp_sdk_python-0.10.2 → macp_sdk_python-0.12.1}/src/macp_sdk/__init__.py

@@ -1,4 +1,6 @@
+import warnings
 from importlib.metadata import version as _version
+from typing import Any as _Any
 
 from ._logging import configure_logging
 from .auth import AuthConfig
@@ -97,11 +99,11 @@ from .projections import (
     DecisionVoteRecord,
 )
 from .proposal import (
-    AcceptRecord,
+    ProposalAcceptRecord,
     ProposalProjection,
     ProposalRecord,
+    ProposalRejectRecord,
     ProposalSession,
-    RejectRecord,
 )
 from .proto_registry import ProtoRegistry
 from .quorum import ApprovalRequestRecord, BallotRecord, QuorumProjection, QuorumSession
@@ -110,8 +112,8 @@ from .task import (
     TaskCompleteRecord,
     TaskFailRecord,
     TaskProjection,
+    TaskRecord,
     TaskRejectRecord,
-    TaskRequestRecord,
     TaskSession,
     TaskUpdateRecord,
 )
@@ -135,7 +137,7 @@ from .watchers import (
     PolicyChange,
     PolicyWatcher,
     RootsWatcher,
-    SessionLifecycle,
+    SessionLifecycleEvent,
     SessionLifecycleWatcher,
     SignalWatcher,
 )
@@ -176,7 +178,6 @@ __all__ = [
     "UNKNOWN_POLICY_VERSION",
     "UNSUPPORTED_PROTOCOL_VERSION",
     "AbstentionRules",
-    "AcceptRecord",
     "AckFailure",
     "ApprovalRequestRecord",
     "AuthConfig",
@@ -211,19 +212,20 @@ __all__ = [
     "PolicyChange",
     "PolicyWatcher",
     "ProjectionAnomaly",
+    "ProposalAcceptRecord",
     "ProposalAcceptanceRules",
     "ProposalProjection",
     "ProposalRecord",
+    "ProposalRejectRecord",
     "ProposalSession",
     "ProtoRegistry",
     "QuorumProjection",
     "QuorumSession",
     "QuorumThreshold",
-    "RejectRecord",
     "RejectionRules",
     "RetryPolicy",
     "RootsWatcher",
-    "SessionLifecycle",
+    "SessionLifecycleEvent",
     "SessionLifecycleWatcher",
     "SignalWatcher",
     "TaskAssignmentRules",
@@ -231,8 +233,8 @@ __all__ = [
     "TaskCompletionRules",
     "TaskFailRecord",
     "TaskProjection",
+    "TaskRecord",
     "TaskRejectRecord",
-    "TaskRequestRecord",
     "TaskSession",
     "TaskUpdateRecord",
     "VotingRules",
@@ -273,3 +275,51 @@ __all__ = [
     "validate_ttl_ms",
     "validate_vote",
 ]
+
+# ── Deprecated aliases (issue #103 / multiagentcoordinationprotocol#135) ─────
+#
+# Kept out of __all__ deliberately -- a deprecated name should not appear in
+# `from macp_sdk import *` or in generated API docs. Does not delegate to the
+# defining submodule's own __getattr__ (proposal.py's, watchers.py's): doing
+# so would point the warning's stacklevel at this module's frame instead of
+# the caller's, since `from macp_sdk import OldName` (this top-level package)
+# is the far more common import path -- same reasoning as agent/__init__.py's
+# own alias dict.
+#
+# This module IS a package (`macp_sdk/`, has __path__), like agent/__init__.py.
+# CPython's import machinery (`importlib._bootstrap._handle_fromlist`) probes
+# any fromlist name against a package with `hasattr(module, name)` *before*
+# the `from ... import` statement's own bytecode-level getattr -- so a
+# deprecated name accessed via `from macp_sdk import RejectRecord` triggers
+# this __getattr__ twice (confirmed empirically in Phase 1), not once. Under
+# Python's default warning filters the two are deduplicated by (message,
+# category, location) and a caller sees a single printed line regardless;
+# under a strict `error` filter (as this repo's own test suite runs under)
+# the first `warnings.warn()` call raises immediately, so the second never
+# happens either. Only an explicit `simplefilter("always")` capture (as in
+# this repo's own deprecation tests) observes both. By contrast, resolving
+# the same old name from its *defining* submodule (`macp_sdk.proposal`,
+# `macp_sdk.watchers`, `macp_sdk.task` -- plain files, no __path__) fires
+# this pattern once.
+#
+# One dict, one __getattr__, covering all renamed top-level exports (issue
+# #103 items 3-5, issue #108) -- each entry's defining submodule (proposal.py,
+# watchers.py, task.py) owns its own identical-shaped __getattr__ for direct
+# submodule imports; this one is only reached via the `macp_sdk` top-level
+# package path.
+_DEPRECATED_ALIASES = {
+    "RejectRecord": "ProposalRejectRecord",
+    "AcceptRecord": "ProposalAcceptRecord",
+    "SessionLifecycle": "SessionLifecycleEvent",
+    "TaskRequestRecord": "TaskRecord",
+}
+
+
+def __getattr__(name: str) -> _Any:
+    new_name = _DEPRECATED_ALIASES.get(name)
+    if new_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    warnings.warn(
+        f"{name} is deprecated; use {new_name} instead.", DeprecationWarning, stacklevel=2
+    )
+    return globals()[new_name]

macp_sdk_python-0.12.1/src/macp_sdk/agent/__init__.py

@@ -0,0 +1,110 @@
+import warnings
+from typing import Any
+
+from .cancel_callback import CancelCallbackServer, start_cancel_callback_server
+from .dispatcher import Dispatcher
+from .participant import InitiatorConfig, Participant, ParticipantActions
+from .runner import from_bootstrap
+from .strategies import (
+    CommitmentResult,
+    CommitmentStrategy,
+    EvaluationResult,
+    EvaluationStrategy,
+    VoteResult,
+    VotingStrategy,
+    commitment_handler,
+    evaluation_handler,
+    function_committer,
+    function_evaluator,
+    function_voter,
+    majority_committer,
+    majority_voter,
+    voting_handler,
+)
+from .transports import (
+    GrpcTransportAdapter,
+    HttpTransportAdapter,
+    TransportAdapter,
+)
+from .types import (
+    HandlerContext,
+    IncomingMessage,
+    MessageHandler,
+    PhaseChangeHandler,
+    SessionInfo,
+    TerminalHandler,
+    TerminalResult,
+)
+
+__all__ = [
+    "CancelCallbackServer",
+    "CommitmentResult",
+    "CommitmentStrategy",
+    "Dispatcher",
+    "EvaluationResult",
+    "EvaluationStrategy",
+    "GrpcTransportAdapter",
+    "HandlerContext",
+    "HttpTransportAdapter",
+    "IncomingMessage",
+    "InitiatorConfig",
+    "MessageHandler",
+    "Participant",
+    "ParticipantActions",
+    "PhaseChangeHandler",
+    "SessionInfo",
+    "TerminalHandler",
+    "TerminalResult",
+    "TransportAdapter",
+    "VoteResult",
+    "VotingStrategy",
+    "commitment_handler",
+    "evaluation_handler",
+    "from_bootstrap",
+    "function_committer",
+    "function_evaluator",
+    "function_voter",
+    "majority_committer",
+    "majority_voter",
+    "start_cancel_callback_server",
+    "voting_handler",
+]
+
+# ── Deprecated aliases (issue #103 / multiagentcoordinationprotocol#135) ─────
+#
+# Kept out of __all__ deliberately -- a deprecated name should not appear in
+# `from macp_sdk.agent import *` or in generated API docs. Does not delegate
+# to strategies.py's own __getattr__: doing so would point the warning's
+# stacklevel at this module's frame instead of the caller's, since that's the
+# far more common `from macp_sdk.agent import VoteDecision` import path.
+#
+# This module IS a package (`agent/`, has `__path__`), unlike strategies.py.
+# CPython's import machinery (`importlib._bootstrap._handle_fromlist`) probes
+# any fromlist name against a package with `hasattr(module, name)` *before*
+# the `from ... import` statement's own bytecode-level getattr -- so a
+# deprecated name accessed via `from macp_sdk.agent import VoteDecision`
+# triggers this __getattr__ twice (confirmed empirically), not once. Under
+# Python's default warning filters the two are deduplicated by (message,
+# category, location) and a caller sees a single printed line regardless;
+# under a strict `error` filter (as this repo's own test suite runs under)
+# the first `warnings.warn()` call raises immediately, so the second never
+# happens either. Only an explicit `simplefilter("always")` capture (as in
+# this repo's own deprecation tests) observes both. This is inherent to
+# package-level `__getattr__` and not specific to this alias -- there is no
+# fix that preserves the "re-warn on every plain attribute access" property
+# documented in strategies.py's own alias comment without also suppressing
+# this.
+_DEPRECATED_ALIASES = {
+    "VoteDecision": "VoteResult",
+    "CommitmentDecision": "CommitmentResult",
+}
+
+
+def __getattr__(name: str) -> Any:
+    new_name = _DEPRECATED_ALIASES.get(name)
+    if new_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    warnings.warn(
+        f"{name} is deprecated; use {new_name} instead.", DeprecationWarning, stacklevel=2
+    )
+    return globals()[new_name]

{macp_sdk_python-0.10.2 → macp_sdk_python-0.12.1}/src/macp_sdk/agent/runner.py

@@ -155,9 +155,9 @@ def from_bootstrap(bootstrap_path: str | None = None) -> Participant:
             participants=[str(p) for p in ss.get("participants", participants)],
             ttl_ms=int(ss.get("ttl_ms", 300000)),
             # Runtime v0.5.0 per-session suspension cap; absent → 0 (runtime
-            # default). The TypeScript bootstrap schema does not yet map this
-            # key, so it is Python-only for now; a bootstrap that omits it
-            # behaves identically in both SDKs.
+            # default). macp-sdk-typescript's BootstrapPayload also declares
+            # and maps this key (src/agent/runner.ts:28,103); a bootstrap
+            # that omits it behaves identically in both SDKs.
             max_suspend_ms=int(ss.get("max_suspend_ms", 0)),
             context_id=str(ss.get("context_id", "")),
             extensions=_decode_extensions(ss.get("extensions")),

{macp_sdk_python-0.10.2 → macp_sdk_python-0.12.1}/src/macp_sdk/agent/strategies.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import warnings
 from collections.abc import Callable
 from dataclasses import dataclass
 from typing import Any, Protocol
@@ -86,7 +87,7 @@ def function_evaluator(
 
 
 @dataclass(frozen=True, slots=True)
-class VoteDecision:
+class VoteResult:
     """Result of a voting decision."""
 
     vote: str
@@ -98,7 +99,7 @@ class VotingStrategy(Protocol):
 
     def should_vote(self, projection: Any) -> bool: ...
 
-    def decide_vote(self, projection: Any) -> VoteDecision: ...
+    def decide_vote(self, projection: Any) -> VoteResult: ...
 
 
 def voting_handler(strategy: VotingStrategy) -> MessageHandler:
@@ -132,7 +133,7 @@ def voting_handler(strategy: VotingStrategy) -> MessageHandler:
 
 def function_voter(
     should_vote_fn: Callable[[Any], bool],
-    decide_fn: Callable[[Any], VoteDecision],
+    decide_fn: Callable[[Any], VoteResult],
 ) -> VotingStrategy:
     """Wrap plain functions as a VotingStrategy."""
 
@@ -142,7 +143,7 @@ def function_voter(
         def __init__(
             self,
             should_fn: Callable[[Any], bool],
-            decide_fn: Callable[[Any], VoteDecision],
+            decide_fn: Callable[[Any], VoteResult],
         ) -> None:
             self._should_fn = should_fn
             self._decide_fn = decide_fn
@@ -150,7 +151,7 @@ def function_voter(
         def should_vote(self, projection: Any) -> bool:
             return self._should_fn(projection)
 
-        def decide_vote(self, projection: Any) -> VoteDecision:
+        def decide_vote(self, projection: Any) -> VoteResult:
             return self._decide_fn(projection)
 
     return _FnVoter(should_vote_fn, decide_fn)
@@ -160,7 +161,7 @@ def function_voter(
 
 
 @dataclass(frozen=True, slots=True)
-class CommitmentDecision:
+class CommitmentResult:
     """Result of a commitment decision."""
 
     action: str
@@ -174,7 +175,7 @@ class CommitmentStrategy(Protocol):
 
     def should_commit(self, projection: Any) -> bool: ...
 
-    def decide_commitment(self, projection: Any) -> CommitmentDecision: ...
+    def decide_commitment(self, projection: Any) -> CommitmentResult: ...
 
 
 def commitment_handler(strategy: CommitmentStrategy) -> MessageHandler:
@@ -219,7 +220,7 @@ def commitment_handler(strategy: CommitmentStrategy) -> MessageHandler:
 
 def function_committer(
     should_commit_fn: Callable[[Any], bool],
-    decide_fn: Callable[[Any], CommitmentDecision],
+    decide_fn: Callable[[Any], CommitmentResult],
 ) -> CommitmentStrategy:
     """Wrap plain functions as a CommitmentStrategy."""
 
@@ -229,7 +230,7 @@ def function_committer(
         def __init__(
             self,
             should_fn: Callable[[Any], bool],
-            decide_fn: Callable[[Any], CommitmentDecision],
+            decide_fn: Callable[[Any], CommitmentResult],
         ) -> None:
             self._should_fn = should_fn
             self._decide_fn = decide_fn
@@ -237,7 +238,7 @@ def function_committer(
         def should_commit(self, projection: Any) -> bool:
             return self._should_fn(projection)
 
-        def decide_commitment(self, projection: Any) -> CommitmentDecision:
+        def decide_commitment(self, projection: Any) -> CommitmentResult:
             return self._decide_fn(projection)
 
     return _FnCommitter(should_commit_fn, decide_fn)
@@ -286,10 +287,10 @@ def majority_voter(
             evaluations = getattr(projection, "evaluations", None)
             return bool(evaluations)
 
-        def decide_vote(self, projection: Any) -> VoteDecision:
+        def decide_vote(self, projection: Any) -> VoteResult:
             evaluations = list(getattr(projection, "evaluations", None) or [])
             if not evaluations:
-                return VoteDecision(vote="ABSTAIN", reason="no evaluations to decide from")
+                return VoteResult(vote="ABSTAIN", reason="no evaluations to decide from")
             # The most recently evaluated proposal is the one being voted on.
             proposal_id = evaluations[-1].proposal_id
             qualifying = [
@@ -298,21 +299,21 @@ def majority_voter(
                 if e.proposal_id == proposal_id and e.recommendation.upper() != "REVIEW"
             ]
             if not qualifying:
-                return VoteDecision(
+                return VoteResult(
                     vote="ABSTAIN",
                     reason=f"no qualifying evaluations for {proposal_id!r}",
                 )
             approvals = sum(1 for e in qualifying if e.recommendation.upper() == "APPROVE")
             ratio = approvals / len(qualifying)
             if ratio >= self._threshold:
-                return VoteDecision(
+                return VoteResult(
                     vote="APPROVE",
                     reason=(
                         f"{approvals}/{len(qualifying)} evaluations approve "
                         f"{proposal_id!r} (>= {self._threshold:.0%})"
                     ),
                 )
-            return VoteDecision(
+            return VoteResult(
                 vote="ABSTAIN",
                 reason=(
                     f"{approvals}/{len(qualifying)} evaluations approve "
@@ -355,9 +356,9 @@ def majority_committer(
                 return False
             return projection.majority_winner() is not None
 
-        def decide_commitment(self, projection: Any) -> CommitmentDecision:
+        def decide_commitment(self, projection: Any) -> CommitmentResult:
             winner = projection.majority_winner()
-            return CommitmentDecision(
+            return CommitmentResult(
                 action=self._action,
                 authority_scope=self._scope,
                 reason=f"majority winner: {winner}",
@@ -365,3 +366,34 @@ def majority_committer(
             )
 
     return _MajorityCommitter(quorum_size, action, authority_scope)
+
+
+# ── Deprecated aliases (issue #103 / multiagentcoordinationprotocol#135) ─────
+#
+# ``VoteDecision``/``CommitmentDecision`` are the pre-rename names, kept as
+# module-level lazy aliases (PEP 562) for one minor version, removed at this
+# SDK's next major. A plain assignment (``VoteDecision = VoteResult``) would
+# be silent; a wrapper subclass would fight ``frozen=True, slots=True``. This
+# module has no ``__path__`` (a plain file, not a package), so CPython's
+# ``from ... import VoteDecision`` resolves via a single ``getattr`` call --
+# the warning fires exactly once per such import, not per call. (Contrast
+# ``agent/__init__.py``'s own alias dict: a *package* import goes through an
+# extra internal ``hasattr`` probe first, firing this pattern twice -- see
+# the comment there.) Plain attribute access (``strategies.VoteDecision``,
+# no ``from`` import) is not cached in ``globals()`` and re-warns on every
+# such access -- the returned object ``is`` its ``*Result`` counterpart
+# either way.
+_DEPRECATED_ALIASES = {
+    "VoteDecision": "VoteResult",
+    "CommitmentDecision": "CommitmentResult",
+}
+
+
+def __getattr__(name: str) -> Any:
+    new_name = _DEPRECATED_ALIASES.get(name)
+    if new_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    warnings.warn(
+        f"{name} is deprecated; use {new_name} instead.", DeprecationWarning, stacklevel=2
+    )
+    return globals()[new_name]

{macp_sdk_python-0.10.2 → macp_sdk_python-0.12.1}/src/macp_sdk/base_projection.py

@@ -8,28 +8,27 @@ from macp.v1 import core_pb2, envelope_pb2
 
 from ._logging import logger
 
-# Cross-SDK contract with macp-sdk-typescript#55 — these two string values are
-# part of the wire-adjacent public API and must match the TypeScript SDK
-# byte-for-byte. They are also the two kinds pinned by the parity manifest
+# Cross-SDK contract with macp-sdk-typescript#55 — these four string values
+# are part of the wire-adjacent public API and must match the TypeScript SDK
+# byte-for-byte. They are also the four kinds pinned by the parity manifest
 # (schemas/parity/contract.json's projection_anomaly.kinds) as of contract
-# 1.1.1 -- an implementation both SDKs already agreed on.
+# 1.2.0 -- an implementation both SDKs now agree on.
 ANOMALY_DUPLICATE_VOTE = "duplicate_vote"  # RFC-MACP-0007 §5.3
 ANOMALY_DUPLICATE_BALLOT = "duplicate_ballot"  # RFC-MACP-0011 §5
 
 # Issue #94 (spec issue #148): whether a discarded competing TaskAccept or an
-# already-settled Handoff message should record an anomaly was, until now, an
-# open question the parity manifest deliberately left unpinned -- six call
-# sites in macp-sdk-typescript were marked "frozen pending cross-SDK
-# agreement with macp-sdk-python". This SDK adopts these two kinds
-# unilaterally as its side of that agreement (tracked via a matching issue
-# filed against macp-sdk-typescript, proposing the same two names) -- they
-# are NOT yet in the parity manifest's kinds list, and must not be asserted
-# against it until macp-sdk-typescript lands its matching side and the
-# manifest is bumped (a MINOR contract_version bump, per its versioning
-# rule). One kind per *mode* (not per cause): both cover only an
-# already-settled discard, never an unknown-subject-id discard -- an unknown
-# task_id/handoff_id can legitimately mean a projection that joined
-# mid-session, which is not caller misuse, so no kind is recorded for it.
+# already-settled Handoff message should record an anomaly was an open
+# question the parity manifest deliberately left unpinned -- six call sites
+# in macp-sdk-typescript were marked "frozen pending cross-SDK agreement
+# with macp-sdk-python". This SDK adopted these two kinds as its side of
+# that agreement in PR #95; macp-sdk-typescript landed the matching side in
+# its PR #134; the manifest bumped to contract 1.2.0 (spec PR #158) to
+# mirror the now-settled agreement, and both kinds are pinned by
+# tests/parity/test_contract.py accordingly. One kind per *mode* (not per
+# cause): both cover only an already-settled discard, never an
+# unknown-subject-id discard -- an unknown task_id/handoff_id can
+# legitimately mean a projection that joined mid-session, which is not
+# caller misuse, so no kind is recorded for it.
 ANOMALY_DUPLICATE_TASK_ACCEPT = "duplicate_task_accept"  # RFC-MACP-0009 §5 rule 3a
 ANOMALY_SETTLED_HANDOFF = "settled_handoff"  # RFC-MACP-0010 §5 rule 4 / §5.1(4)
 
@@ -43,10 +42,9 @@ class ProjectionAnomaly:
     Do not rename, reorder, or extend the field set without coordinating
     there first.
 
-    ``kind`` values in the parity manifest (agreed by both SDKs):
-    ``ANOMALY_DUPLICATE_VOTE``, ``ANOMALY_DUPLICATE_BALLOT``. ``kind`` values
-    this SDK also records, pending macp-sdk-typescript landing a matching
-    kind (issue #94): ``ANOMALY_DUPLICATE_TASK_ACCEPT``,
+    ``kind`` values, all four pinned by the parity manifest (agreed by both
+    SDKs) as of contract 1.2.0: ``ANOMALY_DUPLICATE_VOTE``,
+    ``ANOMALY_DUPLICATE_BALLOT``, ``ANOMALY_DUPLICATE_TASK_ACCEPT``,
     ``ANOMALY_SETTLED_HANDOFF`` -- see those constants' own comments.
 
     Honesty clause: this records an **observation**, not a spec-violation

{macp_sdk_python-0.10.2 → macp_sdk_python-0.12.1}/src/macp_sdk/handoff.py

@@ -30,9 +30,11 @@ class HandoffRecord:
     declined_by: str | None
     # True when the acceptance was an implicit accept synthesized by the
     # runtime (RFC-MACP-0010 §5.1) rather than an explicit client HandoffAccept.
-    # Runtime >= 0.8.0 emits these automatically for every session (no
-    # server-side opt-in exists) when an offer's implicit_accept_timeout_ms
-    # elapses unactioned. Client-submitted accepts are always
+    # Runtime >= 0.8.0 emits these only for sessions whose bound governance
+    # policy declares a non-zero ``acceptance.implicit_accept_timeout_ms``
+    # (RFC-MACP-0010 §5.1, RFC-MACP-0012 §4.5), once that timeout elapses
+    # unactioned; with no policy bound the timeout resolves to 0 and no
+    # implicit accept ever fires. Client-submitted accepts are always
     # ``implicit=False`` (the runtime rejects a forged True).
     implicit: bool = False
 
@@ -177,9 +179,10 @@ class HandoffProjection(BaseProjection):
         """True if *handoff_id* was accepted by a runtime implicit accept.
 
         Distinguishes a timeout-driven implicit accept (RFC-MACP-0010 §5.1)
-        from an explicit client ``HandoffAccept``. Runtime >= 0.8.0 emits
-        these automatically for every session once an offer's
-        ``implicit_accept_timeout_ms`` elapses unactioned.
+        from an explicit client ``HandoffAccept``. Runtime >= 0.8.0 emits one
+        only when the session's bound governance policy declares a non-zero
+        ``acceptance.implicit_accept_timeout_ms`` and that timeout elapses
+        unactioned; sessions with no such policy never see one.
         """
         handoff = self.handoffs.get(handoff_id)
         return handoff is not None and handoff.status == "accepted" and handoff.implicit
@@ -275,7 +278,7 @@ class HandoffSession(BaseSession):
         # ``implicit=true`` for runtime-synthesized accepts and the runtime
         # rejects a client-submitted True. Client accepts always leave the
         # field at its proto3 default (False). See the regression test in
-        # tests/unit/test_handoff.py.
+        # tests/unit/test_absorb_runtime_v050.py.
         validate_required_field("handoff_id", handoff_id)
         payload = handoff_pb2.HandoffAcceptPayload(
             handoff_id=handoff_id,

{macp_sdk_python-0.10.2 → macp_sdk_python-0.12.1}/src/macp_sdk/proposal.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
+import warnings
 from dataclasses import dataclass
+from typing import Any
 
 from macp.modes.proposal.v1 import proposal_pb2
 from macp.v1 import envelope_pb2
@@ -25,12 +27,27 @@ class ProposalRecord:
     summary: str
     proposer: str
     supersedes: str  # "" if original
-    status: str  # "open" | "accepted" | "rejected" | "withdrawn"
+    # Reachable values only. An Accept is recorded on the projection's
+    # ``accepts`` list (and surfaced via ``accepted_proposal`` /
+    # ``is_accepted``), never on this field -- no code path assigns
+    # "accepted" here. A non-terminal Reject likewise leaves this "open";
+    # only ``terminal=True`` sets "rejected".
+    #
+    # That is by design, not an omission (issue #112). Acceptance is a
+    # per-sender, supersedable relation (RFC-MACP-0008 §5 rule 5), not a
+    # per-proposal fact, so a scalar field here cannot hold it: "alice
+    # accepts p2 while bob still accepts p1" is a legal state. This mirrors
+    # the runtime, whose ``ProposalDisposition`` is {Live, Withdrawn} with
+    # acceptance in a separate ``accepts`` map, and typescript-sdk's
+    # ``projections/proposal.ts``, which also never assigns "accepted".
+    # ``task.py``/``handoff.py`` do set "accepted" because their acceptance
+    # is one actor claiming one slot. See docs/modes/proposal.md.
+    status: str  # "open" | "rejected" | "withdrawn"
     tags: list[str]
 
 
 @dataclass(slots=True)
-class RejectRecord:
+class ProposalRejectRecord:
     proposal_id: str
     reason: str
     sender: str
@@ -38,7 +55,7 @@ class RejectRecord:
 
 
 @dataclass(slots=True)
-class AcceptRecord:
+class ProposalAcceptRecord:
     proposal_id: str
     reason: str
     sender: str
@@ -58,8 +75,8 @@ class ProposalProjection(BaseProjection):
         super().__init__()
         self.phase = "Negotiating"
         self.proposals: dict[str, ProposalRecord] = {}
-        self.accepts: list[AcceptRecord] = []
-        self.rejections: list[RejectRecord] = []
+        self.accepts: list[ProposalAcceptRecord] = []
+        self.rejections: list[ProposalRejectRecord] = []
         # Tracks each sender's most recent Accept, so a later Accept from the
         # same sender supersedes an earlier one (RFC-MACP-0008 §5 rule 5).
         # `self.accepts` remains the full audit trail; this is the derived
@@ -102,7 +119,7 @@ class ProposalProjection(BaseProjection):
             p = proposal_pb2.AcceptPayload()
             p.ParseFromString(envelope.payload)
             self.accepts.append(
-                AcceptRecord(
+                ProposalAcceptRecord(
                     proposal_id=p.proposal_id,
                     reason=p.reason,
                     sender=envelope.sender,
@@ -115,7 +132,7 @@ class ProposalProjection(BaseProjection):
             p = proposal_pb2.RejectPayload()
             p.ParseFromString(envelope.payload)
             self.rejections.append(
-                RejectRecord(
+                ProposalRejectRecord(
                     proposal_id=p.proposal_id,
                     reason=p.reason,
                     sender=envelope.sender,
@@ -326,3 +343,29 @@ class ProposalSession(BaseSession):
             payload=serialize_message(payload),
         )
         return self._send_and_track(envelope, auth=auth)
+
+
+# ── Deprecated aliases (issue #103 / multiagentcoordinationprotocol#135) ─────
+#
+# ``RejectRecord``/``AcceptRecord`` are the pre-rename names, kept as
+# module-level lazy aliases (PEP 562) for one minor version, removed at this
+# SDK's next major. Same mechanism and reasoning as ``agent/strategies.py``'s
+# own alias dict -- see the comment there for the full rationale (plain
+# assignment is silent; a wrapper subclass is unnecessary complexity here
+# too). This module has no ``__path__`` (a plain file, not a package), so
+# ``from macp_sdk.proposal import RejectRecord`` resolves via a single
+# ``getattr`` call -- the warning fires exactly once per such import.
+_DEPRECATED_ALIASES = {
+    "RejectRecord": "ProposalRejectRecord",
+    "AcceptRecord": "ProposalAcceptRecord",
+}
+
+
+def __getattr__(name: str) -> Any:
+    new_name = _DEPRECATED_ALIASES.get(name)
+    if new_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    warnings.warn(
+        f"{name} is deprecated; use {new_name} instead.", DeprecationWarning, stacklevel=2
+    )
+    return globals()[new_name]

{macp_sdk_python-0.10.2 → macp_sdk_python-0.12.1}/src/macp_sdk/task.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import warnings
 from dataclasses import dataclass
+from typing import Any
 
 from macp.modes.task.v1 import task_pb2
 from macp.v1 import envelope_pb2
@@ -19,12 +20,17 @@ from .validation import validate_required_field
 
 
 @dataclass(slots=True)
-class TaskRequestRecord:
+class TaskRecord:
     task_id: str
     title: str
     instructions: str
     requested_assignee: str
     requester: str
+    status: str = "requested"
+    progress: float = 0.0
+    assignee: str | None = None
+    deadline_unix_ms: int = 0
+    input: bytes = b""
 
 
 @dataclass(slots=True)
@@ -78,18 +84,16 @@ class TaskProjection(BaseProjection):
     def __init__(self) -> None:
         super().__init__()
         self.phase = "Pending"
-        self.tasks: dict[str, TaskRequestRecord] = {}
+        self.tasks: dict[str, TaskRecord] = {}
         self.updates: list[TaskUpdateRecord] = []
+        self.rejections: list[TaskRejectRecord] = []
         self.completions: list[TaskCompleteRecord] = []
         self.failures: list[TaskFailRecord] = []
-        # Per-task mutable state (reporting view — what a caller reads)
-        self._assignees: dict[str, str] = {}  # task_id -> assignee
-        self._statuses: dict[str, str] = {}  # task_id -> status
-        self._progress: dict[str, float] = {}  # task_id -> progress
         # Session-scoped single-assignee slot (RFC-MACP-0009 §5 rule 3: "Only
         # one assignee may become active for the Session in base v1" — scoped
         # to the whole session, not to a task_id). This is the exclusivity
-        # guard; ``_assignees`` above remains the per-task reporting view.
+        # guard; each task's own ``assignee`` field on ``self.tasks`` remains
+        # the per-task reporting view.
         # Mirrors typescript-sdk's ``activeAssignment`` field.
         self.active_assignment: tuple[str, str] | None = None  # (sender, task_id)
 
@@ -99,15 +103,20 @@ class TaskProjection(BaseProjection):
         if mt == "TaskRequest":
             p = task_pb2.TaskRequestPayload()
             p.ParseFromString(envelope.payload)
-            self.tasks[p.task_id] = TaskRequestRecord(
+            self.tasks[p.task_id] = TaskRecord(
                 task_id=p.task_id,
                 title=p.title,
                 instructions=p.instructions,
                 requested_assignee=p.requested_assignee,
                 requester=envelope.sender,
+                status="requested",
+                progress=0.0,
+                assignee=None,
+                deadline_unix_ms=p.deadline_unix_ms,
+                input=p.input,
             )
-            self._statuses[p.task_id] = "requested"
-            self._progress[p.task_id] = 0.0
+            if self.active_assignment is not None and self.active_assignment[1] == p.task_id:
+                self.active_assignment = None
             self._set_phase("Requested")
             return
 
@@ -118,8 +127,8 @@ class TaskProjection(BaseProjection):
                 if self.active_assignment is None:
                     assignee = p.assignee or envelope.sender
                     self.active_assignment = (envelope.sender, p.task_id)
-                    self._assignees[p.task_id] = assignee
-                    self._statuses[p.task_id] = "accepted"
+                    self.tasks[p.task_id].assignee = assignee
+                    self.tasks[p.task_id].status = "accepted"
                     self._set_phase("InProgress")
                 else:
                     # RFC-MACP-0009 §5 rule 3a: a second TaskAccept while the
@@ -146,15 +155,27 @@ class TaskProjection(BaseProjection):
         if mt == "TaskReject":
             p = task_pb2.TaskRejectPayload()
             p.ParseFromString(envelope.payload)
-            # Status write is gated on the task being known (task.ts:136's
-            # `if (task)`); slot-freeing is a SEPARATE, unconditional check on
-            # sender alone (task.ts:158-161) — a slot-holder's TaskReject
-            # naming an unknown task_id still frees their held slot.
+            # The rejection record is kept unconditionally (mirrors updates/
+            # completions/failures' own audit-trail convention); only the
+            # per-task status write is gated on the task being known
+            # (task.ts:136's `if (task)`). Slot-freeing is a SEPARATE,
+            # unconditional check on sender alone (task.ts:158-161) — a
+            # slot-holder's TaskReject naming an unknown task_id still frees
+            # their held slot.
+            self.rejections.append(
+                TaskRejectRecord(
+                    task_id=p.task_id,
+                    assignee=p.assignee or envelope.sender,
+                    reason=p.reason,
+                )
+            )
             if p.task_id in self.tasks:
-                self._statuses[p.task_id] = "rejected"
+                self.tasks[p.task_id].status = "rejected"
             slot = self.active_assignment
             if slot is not None and slot[0] == envelope.sender:
-                self._assignees.pop(slot[1], None)
+                held = self.tasks.get(slot[1])
+                if held is not None:
+                    held.assignee = None
                 self.active_assignment = None
             return
 
@@ -173,8 +194,8 @@ class TaskProjection(BaseProjection):
                 )
             )
             if p.task_id in self.tasks:
-                self._statuses[p.task_id] = "in_progress"
-                self._progress[p.task_id] = p.progress
+                self.tasks[p.task_id].status = "in_progress"
+                self.tasks[p.task_id].progress = p.progress
             return
 
         if mt == "TaskComplete":
@@ -189,8 +210,8 @@ class TaskProjection(BaseProjection):
                 )
             )
             if p.task_id in self.tasks:
-                self._statuses[p.task_id] = "completed"
-                self._progress[p.task_id] = 1.0
+                self.tasks[p.task_id].status = "completed"
+                self.tasks[p.task_id].progress = 1.0
                 self._set_phase("Completed")
             return
 
@@ -207,32 +228,46 @@ class TaskProjection(BaseProjection):
                 )
             )
             if p.task_id in self.tasks:
-                self._statuses[p.task_id] = "failed"
+                self.tasks[p.task_id].status = "failed"
                 self._set_phase("Failed")
 
     # -- State query helpers --
 
-    def get_task(self, task_id: str) -> TaskRequestRecord | None:
-        """Return the task request record for *task_id*, or None."""
+    def get_task(self, task_id: str) -> TaskRecord | None:
+        """Return the task's current record for *task_id*, or None.
+
+        Reflects live state, not just the original request: ``status``,
+        ``progress``, and ``assignee`` update in place as later messages
+        (TaskAccept/TaskUpdate/TaskComplete/TaskFail/TaskReject) arrive.
+
+        The returned object is this projection's own record, not a copy --
+        treat it as read-only. Mutating it mutates projection state directly
+        (same contract as :meth:`ProposalProjection.live_proposals`'s
+        returned records).
+        """
         return self.tasks.get(task_id)
 
     def current_assignee(self, task_id: str) -> str | None:
         """Return the current assignee for *task_id*, or None if unassigned."""
-        return self._assignees.get(task_id)
+        rec = self.tasks.get(task_id)
+        return rec.assignee if rec is not None else None
 
     def current_status(self, task_id: str) -> str | None:
         """Return the current status for *task_id*, or None if unknown."""
-        return self._statuses.get(task_id)
+        rec = self.tasks.get(task_id)
+        return rec.status if rec is not None else None
 
     def is_accepted(self, task_id: str) -> bool:
-        status = self._statuses.get(task_id)
-        return status == "accepted" or status == "in_progress"
+        rec = self.tasks.get(task_id)
+        return rec is not None and rec.status in ("accepted", "in_progress")
 
     def is_completed(self, task_id: str) -> bool:
-        return self._statuses.get(task_id) == "completed"
+        rec = self.tasks.get(task_id)
+        return rec is not None and rec.status == "completed"
 
     def is_failed(self, task_id: str) -> bool:
-        return self._statuses.get(task_id) == "failed"
+        rec = self.tasks.get(task_id)
+        return rec is not None and rec.status == "failed"
 
     def is_retryable(self, task_id: str) -> bool:
         """True if the task failed with ``retryable=True``."""
@@ -240,15 +275,20 @@ class TaskProjection(BaseProjection):
 
     def progress_of(self, task_id: str) -> float:
         """Return the latest progress value for *task_id*, or 0 if unknown."""
-        return self._progress.get(task_id, 0.0)
+        rec = self.tasks.get(task_id)
+        return rec.progress if rec is not None else 0.0
 
     def latest_progress(self) -> float | None:
         return self.updates[-1].progress if self.updates else None
 
-    def active_tasks(self) -> list[TaskRequestRecord]:
-        """Return task records that are not in a terminal state."""
+    def active_tasks(self) -> list[TaskRecord]:
+        """Return task records that are not in a terminal state.
+
+        Returns this projection's own records, not copies -- see
+        :meth:`get_task`'s docstring for the read-only contract.
+        """
         active_statuses = {"requested", "accepted", "in_progress"}
-        return [t for t in self.tasks.values() if self._statuses.get(t.task_id) in active_statuses]
+        return [t for t in self.tasks.values() if t.status in active_statuses]
 
 
 # ---------------------------------------------------------------------------
@@ -476,3 +516,27 @@ class TaskSession(BaseSession):
             stacklevel=2,
         )
         return self.fail_task(*args, **kwargs)  # type: ignore[arg-type]
+
+
+# ── Deprecated aliases (issue #108) ───────────────────────────────────────
+#
+# ``TaskRequestRecord`` is the pre-rename name, kept as a module-level lazy
+# alias (PEP 562) for one minor version, removed at this SDK's next major.
+# Same mechanism and reasoning as ``proposal.py``'s own alias dict -- see the
+# comment there for the full rationale. This module has no ``__path__`` (a
+# plain file, not a package), so ``from macp_sdk.task import
+# TaskRequestRecord`` resolves via a single ``getattr`` call -- the warning
+# fires exactly once per such import.
+_DEPRECATED_ALIASES = {
+    "TaskRequestRecord": "TaskRecord",
+}
+
+
+def __getattr__(name: str) -> Any:
+    new_name = _DEPRECATED_ALIASES.get(name)
+    if new_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    warnings.warn(
+        f"{name} is deprecated; use {new_name} instead.", DeprecationWarning, stacklevel=2
+    )
+    return globals()[new_name]

{macp_sdk_python-0.10.2 → macp_sdk_python-0.12.1}/src/macp_sdk/watchers.py

@@ -8,6 +8,7 @@ Each watcher provides three consumption patterns:
 
 from __future__ import annotations
 
+import warnings
 from collections.abc import Callable, Iterator
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any
@@ -26,11 +27,12 @@ class PolicyChange:
 
 
 @dataclass(slots=True)
-class SessionLifecycle:
+class SessionLifecycleEvent:
     """A single session lifecycle event from ``WatchSessions``.
 
-    Runtime event types (per ``SessionLifecycleEvent.EventType``, since
-    macp-proto 0.1.3): ``CREATED`` on SessionStart acceptance (also emitted
+    Runtime event types (per the wire message's own
+    ``SessionLifecycleEvent.EventType`` enum, since macp-proto 0.1.3):
+    ``CREATED`` on SessionStart acceptance (also emitted
     for pre-existing sessions at subscribe time), ``RESOLVED`` on
     mode-determined terminal outcome, ``EXPIRED`` on TTL/policy expiry,
     ``CANCELLED`` on an accepted ``CancelSession`` (previously surfaced as
@@ -158,7 +160,8 @@ _SESSION_EVENT_PREFIX = "EVENT_TYPE_"
 
 
 def _session_event_name(event_type: int) -> str:
-    """Map ``SessionLifecycleEvent.EventType`` enum ints to short string names.
+    """Map the wire message's ``SessionLifecycleEvent.EventType`` enum ints to
+    short string names.
 
     The proto enum spells values as ``EVENT_TYPE_CREATED``; strip the
     prefix so consumers can compare against ``"CREATED"`` without
@@ -176,7 +179,7 @@ class SessionLifecycleWatcher:
     """Watch for session lifecycle events from the runtime.
 
     Wraps ``MacpClient.watch_sessions()`` and normalises each response into
-    a ``SessionLifecycle`` record carrying the event type as a short
+    a ``SessionLifecycleEvent`` record carrying the event type as a short
     string (``CREATED`` / ``RESOLVED`` / ``EXPIRED`` / ``CANCELLED`` /
     ``SUSPENDED`` / ``RESUMED``) and the full ``SessionMetadata``. The
     runtime emits an initial CREATED event for every already-open session at
@@ -188,24 +191,24 @@ class SessionLifecycleWatcher:
         self._client = client
         self._auth = auth
 
-    def changes(self) -> Iterator[SessionLifecycle]:
-        """Yield ``SessionLifecycle`` items from the runtime stream."""
+    def changes(self) -> Iterator[SessionLifecycleEvent]:
+        """Yield ``SessionLifecycleEvent`` items from the runtime stream."""
         for response in self._client.watch_sessions(auth=self._auth):
             event = getattr(response, "event", None)
             if event is None:
                 continue
-            yield SessionLifecycle(
+            yield SessionLifecycleEvent(
                 event_type=_session_event_name(event.event_type),
                 observed_at_unix_ms=event.observed_at_unix_ms,
                 session=event.session,
             )
 
-    def watch(self, handler: Callable[[SessionLifecycle], None]) -> None:
+    def watch(self, handler: Callable[[SessionLifecycleEvent], None]) -> None:
         """Block and invoke *handler* for each lifecycle event."""
         for change in self.changes():
             handler(change)
 
-    def next_change(self) -> SessionLifecycle:
+    def next_change(self) -> SessionLifecycleEvent:
         """Pull a single lifecycle event from the stream and return it."""
         for change in self.changes():
             return change
@@ -236,3 +239,27 @@ class PolicyWatcher:
         for change in self.changes():
             return change
         raise RuntimeError("stream ended before receiving a policy change")
+
+
+# ── Deprecated aliases (issue #103 / multiagentcoordinationprotocol#135) ─────
+#
+# ``SessionLifecycle`` is the pre-rename name, kept as a module-level lazy
+# alias (PEP 562) for one minor version, removed at this SDK's next major.
+# Same mechanism and reasoning as ``agent/strategies.py``'s own alias dict --
+# see the comment there for the full rationale. This module has no
+# ``__path__`` (a plain file, not a package), so
+# ``from macp_sdk.watchers import SessionLifecycle`` resolves via a single
+# ``getattr`` call -- the warning fires exactly once per such import.
+_DEPRECATED_ALIASES = {
+    "SessionLifecycle": "SessionLifecycleEvent",
+}
+
+
+def __getattr__(name: str) -> Any:
+    new_name = _DEPRECATED_ALIASES.get(name)
+    if new_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    warnings.warn(
+        f"{name} is deprecated; use {new_name} instead.", DeprecationWarning, stacklevel=2
+    )
+    return globals()[new_name]

{macp_sdk_python-0.10.2 → macp_sdk_python-0.12.1}/src/macp_sdk_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: macp-sdk-python
-Version: 0.10.2
+Version: 0.12.1
 Summary: Python SDK for the MACP Rust runtime
 Author-email: Multi-Agent Coordination Protocol <macp@multiagentcoordinationprotocol.org>
 License: Apache-2.0

macp_sdk_python-0.10.2/src/macp_sdk/agent/__init__.py

@@ -1,68 +0,0 @@
-from .cancel_callback import CancelCallbackServer, start_cancel_callback_server
-from .dispatcher import Dispatcher
-from .participant import InitiatorConfig, Participant, ParticipantActions
-from .runner import from_bootstrap
-from .strategies import (
-    CommitmentDecision,
-    CommitmentStrategy,
-    EvaluationResult,
-    EvaluationStrategy,
-    VoteDecision,
-    VotingStrategy,
-    commitment_handler,
-    evaluation_handler,
-    function_committer,
-    function_evaluator,
-    function_voter,
-    majority_committer,
-    majority_voter,
-    voting_handler,
-)
-from .transports import (
-    GrpcTransportAdapter,
-    HttpTransportAdapter,
-    TransportAdapter,
-)
-from .types import (
-    HandlerContext,
-    IncomingMessage,
-    MessageHandler,
-    PhaseChangeHandler,
-    SessionInfo,
-    TerminalHandler,
-    TerminalResult,
-)
-
-__all__ = [
-    "CancelCallbackServer",
-    "CommitmentDecision",
-    "CommitmentStrategy",
-    "Dispatcher",
-    "EvaluationResult",
-    "EvaluationStrategy",
-    "GrpcTransportAdapter",
-    "HandlerContext",
-    "HttpTransportAdapter",
-    "IncomingMessage",
-    "InitiatorConfig",
-    "MessageHandler",
-    "Participant",
-    "ParticipantActions",
-    "PhaseChangeHandler",
-    "SessionInfo",
-    "TerminalHandler",
-    "TerminalResult",
-    "TransportAdapter",
-    "VoteDecision",
-    "VotingStrategy",
-    "commitment_handler",
-    "evaluation_handler",
-    "from_bootstrap",
-    "function_committer",
-    "function_evaluator",
-    "function_voter",
-    "majority_committer",
-    "majority_voter",
-    "start_cancel_callback_server",
-    "voting_handler",
-]