macp-sdk-python 0.3.0__tar.gz → 0.4.0__tar.gz

{macp_sdk_python-0.3.0/src/macp_sdk_python.egg-info → macp_sdk_python-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: macp-sdk-python
-Version: 0.3.0
+Version: 0.4.0
 Summary: Python SDK for the MACP Rust runtime
 Author-email: OpenAI <support@openai.com>
 License: Apache-2.0
@@ -15,9 +15,9 @@ Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: grpcio>=1.74.0
+Requires-Dist: grpcio>=1.81.1
 Requires-Dist: protobuf>=5.27.0
-Requires-Dist: macp-proto<0.2.0,>=0.1.2
+Requires-Dist: macp-proto<0.2.0,>=0.1.3
 Provides-Extra: dev
 Requires-Dist: grpcio-tools>=1.74.0; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"
@@ -165,6 +165,7 @@ Business logic — voting rules, AI decision heuristics, policy enforcement —
 
 - `GetSession` returns metadata only (not mode state/transcript) — hence the local projection pattern; use `StreamSession` + `send_subscribe` for the full transcript
 - `StreamSession` is scoped to one session per stream; use `MacpStream.send_subscribe(session_id)` (RFC-MACP-0006-A1, since SDK 0.2.3 / `macp-proto 0.1.2`) to replay accepted history before live broadcast
-- For cross-session observability, use `MacpClient.list_sessions()` and `SessionLifecycleWatcher` (SDK 0.3.0) to enumerate active sessions and stream `CREATED` / `RESOLVED` / `EXPIRED` lifecycle events
+- For cross-session observability, use `MacpClient.list_sessions()` and `SessionLifecycleWatcher` (SDK 0.3.0) to enumerate active sessions and stream `CREATED` / `RESOLVED` / `EXPIRED` / `CANCELLED` / `SUSPENDED` / `RESUMED` lifecycle events
+- Pause and cancel sessions with `MacpClient.suspend_session()` / `resume_session()` / `cancel_session()` (SDK 0.4.0 / `macp-proto 0.1.3`). A suspended session is non-terminal and rejects messages until resumed; an accepted `cancel_session()` now terminates as `CANCELLED` (previously surfaced as `EXPIRED`)
 - `ListRoots` currently returns an empty list and `WatchRoots` idles — the runtime does not yet populate roots
 - Business policy (majority, quorum, veto) belongs in your orchestrator/policy layer

{macp_sdk_python-0.3.0 → macp_sdk_python-0.4.0}/README.md

@@ -131,6 +131,7 @@ Business logic — voting rules, AI decision heuristics, policy enforcement —
 
 - `GetSession` returns metadata only (not mode state/transcript) — hence the local projection pattern; use `StreamSession` + `send_subscribe` for the full transcript
 - `StreamSession` is scoped to one session per stream; use `MacpStream.send_subscribe(session_id)` (RFC-MACP-0006-A1, since SDK 0.2.3 / `macp-proto 0.1.2`) to replay accepted history before live broadcast
-- For cross-session observability, use `MacpClient.list_sessions()` and `SessionLifecycleWatcher` (SDK 0.3.0) to enumerate active sessions and stream `CREATED` / `RESOLVED` / `EXPIRED` lifecycle events
+- For cross-session observability, use `MacpClient.list_sessions()` and `SessionLifecycleWatcher` (SDK 0.3.0) to enumerate active sessions and stream `CREATED` / `RESOLVED` / `EXPIRED` / `CANCELLED` / `SUSPENDED` / `RESUMED` lifecycle events
+- Pause and cancel sessions with `MacpClient.suspend_session()` / `resume_session()` / `cancel_session()` (SDK 0.4.0 / `macp-proto 0.1.3`). A suspended session is non-terminal and rejects messages until resumed; an accepted `cancel_session()` now terminates as `CANCELLED` (previously surfaced as `EXPIRED`)
 - `ListRoots` currently returns an empty list and `WatchRoots` idles — the runtime does not yet populate roots
 - Business policy (majority, quorum, veto) belongs in your orchestrator/policy layer

{macp_sdk_python-0.3.0 → macp_sdk_python-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "macp-sdk-python"
-version = "0.3.0"
+version = "0.4.0"
 description = "Python SDK for the MACP Rust runtime"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -23,14 +23,18 @@ classifiers = [
   "Topic :: Software Development :: Libraries",
 ]
 dependencies = [
-  "grpcio>=1.74.0",
+  # macp-proto 0.1.3's generated gRPC stubs require grpcio>=1.81.1.
+  "grpcio>=1.81.1",
   "protobuf>=5.27.0",
-  # Requires 0.1.2+ for the RFC-MACP-0006-A1 subscribe_session_id /
+  # Requires 0.1.3+ for the suspend/cancel/supersede surface: SuspendSession
+  # /ResumeSession RPCs, SESSION_STATE_SUSPENDED/CANCELLED, the SUSPENDED/
+  # RESUMED/CANCELLED lifecycle events, and CommitmentPayload.supersedes
+  # (CommitmentRef). 0.1.2 added the RFC-MACP-0006-A1 subscribe_session_id /
   # after_sequence fields on StreamSessionRequest (used by MacpStream
-  # .send_subscribe and the gRPC agent transport adapter). 0.1.1 is
-  # the earlier baseline for the context_id / extensions fields on
-  # SessionStartPayload. See docs/contributing.md "Bumping macp-proto".
-  "macp-proto>=0.1.2,<0.2.0",
+  # .send_subscribe and the gRPC agent transport adapter); 0.1.1 is the
+  # earlier baseline for context_id / extensions on SessionStartPayload.
+  # See docs/contributing.md "Bumping macp-proto".
+  "macp-proto>=0.1.3,<0.2.0",
 ]
 
 [project.optional-dependencies]

{macp_sdk_python-0.3.0 → macp_sdk_python-0.4.0}/src/macp_sdk/__init__.py

@@ -19,6 +19,7 @@ from .constants import (
 from .decision import DecisionSession
 from .envelope import (
     build_commitment_payload,
+    build_commitment_ref,
     build_envelope,
     build_progress_payload,
     build_root,
@@ -181,6 +182,7 @@ __all__ = [
     "TaskSession",
     "VotingRules",
     "build_commitment_payload",
+    "build_commitment_ref",
     "build_decision_policy",
     "build_envelope",
     "build_handoff_policy",

{macp_sdk_python-0.3.0 → macp_sdk_python-0.4.0}/src/macp_sdk/base_session.py

@@ -163,9 +163,25 @@ class BaseSession(ABC):
         return self.client.get_session(self.session_id, auth=auth or self.auth)
 
     def cancel(self, *, reason: str = "", auth: AuthConfig | None = None) -> envelope_pb2.Ack:
-        """Cancel the session."""
+        """Cancel the session (terminates as ``CANCELLED`` since proto 0.1.3)."""
         return self.client.cancel_session(self.session_id, reason=reason, auth=auth or self.auth)
 
+    def suspend(self, *, reason: str = "", auth: AuthConfig | None = None) -> envelope_pb2.Ack:
+        """Suspend this session (proto 0.1.3+).
+
+        Moves it to the non-terminal ``SUSPENDED`` state; the runtime rejects
+        messages until :meth:`resume`. Delegates to
+        :meth:`MacpClient.suspend_session`.
+        """
+        return self.client.suspend_session(self.session_id, reason=reason, auth=auth or self.auth)
+
+    def resume(self, *, reason: str = "", auth: AuthConfig | None = None) -> envelope_pb2.Ack:
+        """Resume this suspended session (proto 0.1.3+), restoring ``OPEN``.
+
+        Delegates to :meth:`MacpClient.resume_session`.
+        """
+        return self.client.resume_session(self.session_id, reason=reason, auth=auth or self.auth)
+
     def open_stream(self, *, auth: AuthConfig | None = None) -> MacpStream:
         """Open a bidirectional stream for this session."""
         return self.client.open_stream(auth=auth or self.auth)

{macp_sdk_python-0.3.0 → macp_sdk_python-0.4.0}/src/macp_sdk/client.py

@@ -213,7 +213,7 @@ class MacpClient:
         root_certificates: bytes | None = None,
         default_timeout: float | None = None,
         client_name: str = "macp-sdk-python",
-        client_version: str = "0.3.0",
+        client_version: str = "0.4.0",
     ) -> None:
         if secure is None:
             secure = not allow_insecure
@@ -370,6 +370,13 @@ class MacpClient:
         timeout: float | None = None,
         raise_on_nack: bool = True,
     ) -> envelope_pb2.Ack:
+        """Terminate a session.
+
+        Since runtime 0.4.0 / macp-proto 0.1.3 an accepted cancellation
+        moves the session to ``SESSION_STATE_CANCELLED`` (previously
+        ``EXPIRED``) and surfaces an ``EVENT_TYPE_CANCELLED`` lifecycle
+        event. The returned ``Ack.session_state`` reflects ``CANCELLED``.
+        """
         auth_cfg = self._require_auth(auth)
         request_kwargs: dict[str, object] = {
             "session_id": session_id,
@@ -395,6 +402,66 @@ class MacpClient:
             raise MacpAckError(self._failure_from_ack(ack))
         return ack
 
+    def suspend_session(
+        self,
+        session_id: str,
+        *,
+        reason: str = "",
+        auth: AuthConfig | None = None,
+        timeout: float | None = None,
+        raise_on_nack: bool = True,
+    ) -> envelope_pb2.Ack:
+        """Suspend an open session (macp-proto 0.1.3 / runtime 0.4.0).
+
+        Moves the session to the non-terminal ``SESSION_STATE_SUSPENDED``
+        state and emits an ``EVENT_TYPE_SUSPENDED`` lifecycle event. While
+        suspended the runtime rejects messages sent to the session with a
+        non-OPEN error; call :meth:`resume_session` to return it to OPEN.
+        The returned ``Ack.session_state`` reflects ``SUSPENDED``.
+        """
+        auth_cfg = self._require_auth(auth)
+        try:
+            response = self.stub.SuspendSession(
+                core_pb2.SuspendSessionRequest(session_id=session_id, reason=reason),
+                metadata=self._metadata(auth_cfg),
+                timeout=timeout or self.default_timeout,
+            )
+        except grpc.RpcError as rpc_err:
+            raise MacpTransportError(rpc_err.details() or str(rpc_err)) from rpc_err
+        ack = response.ack
+        if raise_on_nack and not ack.ok:
+            raise MacpAckError(self._failure_from_ack(ack))
+        return ack
+
+    def resume_session(
+        self,
+        session_id: str,
+        *,
+        reason: str = "",
+        auth: AuthConfig | None = None,
+        timeout: float | None = None,
+        raise_on_nack: bool = True,
+    ) -> envelope_pb2.Ack:
+        """Resume a suspended session (macp-proto 0.1.3 / runtime 0.4.0).
+
+        Returns a ``SESSION_STATE_SUSPENDED`` session to
+        ``SESSION_STATE_OPEN`` and emits an ``EVENT_TYPE_RESUMED`` lifecycle
+        event. The returned ``Ack.session_state`` reflects ``OPEN``.
+        """
+        auth_cfg = self._require_auth(auth)
+        try:
+            response = self.stub.ResumeSession(
+                core_pb2.ResumeSessionRequest(session_id=session_id, reason=reason),
+                metadata=self._metadata(auth_cfg),
+                timeout=timeout or self.default_timeout,
+            )
+        except grpc.RpcError as rpc_err:
+            raise MacpTransportError(rpc_err.details() or str(rpc_err)) from rpc_err
+        ack = response.ack
+        if raise_on_nack and not ack.ok:
+            raise MacpAckError(self._failure_from_ack(ack))
+        return ack
+
     def get_manifest(
         self, agent_id: str = "", *, timeout: float | None = None
     ) -> core_pb2.GetManifestResponse:
@@ -452,10 +519,11 @@ class MacpClient:
 
         The runtime emits an initial ``EVENT_TYPE_CREATED`` frame for every
         currently-open session, then live events as sessions transition
-        through ``CREATED``, ``RESOLVED``, and ``EXPIRED``. Each event
-        carries a full ``SessionMetadata`` (including ``context_id`` and
-        ``extension_keys``), so callers can project run state without a
-        follow-up ``get_session``.
+        through ``CREATED``, ``RESOLVED``, ``EXPIRED``, ``CANCELLED``, and
+        the non-terminal ``SUSPENDED`` / ``RESUMED`` pair (the latter three
+        since macp-proto 0.1.3). Each event carries a full
+        ``SessionMetadata`` (including ``context_id`` and ``extension_keys``),
+        so callers can project run state without a follow-up ``get_session``.
         """
         logger.debug("watch_sessions starting")
         auth_cfg = self._require_auth(auth)

{macp_sdk_python-0.3.0 → macp_sdk_python-0.4.0}/src/macp_sdk/envelope.py

@@ -80,6 +80,17 @@ def _has_outcome_positive_field() -> bool:
     return any(f.name == "outcome_positive" for f in core_pb2.CommitmentPayload.DESCRIPTOR.fields)
 
 
+def _has_supersedes_field() -> bool:
+    """Check if the proto schema supports CommitmentPayload.supersedes (>=0.1.3)."""
+    return any(f.name == "supersedes" for f in core_pb2.CommitmentPayload.DESCRIPTOR.fields)
+
+
+def build_commitment_ref(*, session_id: str, commitment_hash: str) -> core_pb2.CommitmentRef:
+    """Build a ``CommitmentRef`` (macp-proto 0.1.3) pointing at a prior
+    commitment, for use as ``build_commitment_payload(supersedes=...)``."""
+    return core_pb2.CommitmentRef(session_id=session_id, commitment_hash=commitment_hash)
+
+
 def build_commitment_payload(
     *,
     action: str,
@@ -90,7 +101,15 @@ def build_commitment_payload(
     configuration_version: str = DEFAULT_CONFIGURATION_VERSION,
     policy_version: str = DEFAULT_POLICY_VERSION,
     outcome_positive: bool | None = None,
+    supersedes: core_pb2.CommitmentRef | None = None,
 ) -> core_pb2.CommitmentPayload:
+    """Build a ``CommitmentPayload``.
+
+    ``supersedes`` (macp-proto 0.1.3) optionally references a prior
+    commitment this one revises, as a ``CommitmentRef`` of
+    ``(session_id, commitment_hash)``. It is absent by default and unrelated
+    to proposal-mode ``supersedes_proposal_id``.
+    """
     if outcome_positive is None:
         outcome_positive = infer_outcome_positive(action)
     kwargs: dict[str, object] = dict(
@@ -104,6 +123,10 @@ def build_commitment_payload(
     )
     if _has_outcome_positive_field():
         kwargs["outcome_positive"] = outcome_positive
+    if supersedes is not None:
+        if not _has_supersedes_field():
+            raise MacpSessionError("CommitmentPayload.supersedes requires macp-proto >= 0.1.3")
+        kwargs["supersedes"] = supersedes
     return core_pb2.CommitmentPayload(**kwargs)
 
 

{macp_sdk_python-0.3.0 → macp_sdk_python-0.4.0}/src/macp_sdk/watchers.py

@@ -29,10 +29,13 @@ class PolicyChange:
 class SessionLifecycle:
     """A single session lifecycle event from ``WatchSessions``.
 
-    Runtime event types (per ``SessionLifecycleEvent.EventType``): ``CREATED``
-    on SessionStart acceptance (also emitted for pre-existing sessions at
-    subscribe time), ``RESOLVED`` on mode-determined terminal outcome,
-    ``EXPIRED`` on TTL expiry or explicit ``CancelSession``.
+    Runtime event types (per ``SessionLifecycleEvent.EventType``, 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
+    ``EXPIRED``), and the non-terminal pair ``SUSPENDED`` / ``RESUMED`` from
+    ``SuspendSession`` / ``ResumeSession``.
     """
 
     event_type: str = "UNSPECIFIED"
@@ -49,12 +52,31 @@ class SessionLifecycle:
 
     @property
     def is_expired(self) -> bool:
+        """``True`` only for TTL/policy expiry; explicit cancellation now
+        surfaces as ``CANCELLED`` — see ``is_cancelled``."""
         return self.event_type == "EXPIRED"
 
+    @property
+    def is_cancelled(self) -> bool:
+        """``True`` for an accepted ``CancelSession`` (terminal)."""
+        return self.event_type == "CANCELLED"
+
+    @property
+    def is_suspended(self) -> bool:
+        """``True`` after ``SuspendSession`` — non-terminal; the session can
+        still ``RESUMED``."""
+        return self.event_type == "SUSPENDED"
+
+    @property
+    def is_resumed(self) -> bool:
+        """``True`` after ``ResumeSession`` returns a suspended session to OPEN."""
+        return self.event_type == "RESUMED"
+
     @property
     def is_terminal(self) -> bool:
-        """``True`` for RESOLVED or EXPIRED — the session won't emit more events."""
-        return self.event_type in ("RESOLVED", "EXPIRED")
+        """``True`` for RESOLVED, EXPIRED, or CANCELLED — the session won't
+        emit more events. ``SUSPENDED`` / ``RESUMED`` are non-terminal."""
+        return self.event_type in ("RESOLVED", "EXPIRED", "CANCELLED")
 
 
 class ModeRegistryWatcher:
@@ -151,10 +173,11 @@ class SessionLifecycleWatcher:
 
     Wraps ``MacpClient.watch_sessions()`` and normalises each response into
     a ``SessionLifecycle`` record carrying the event type as a short
-    string (``CREATED`` / ``RESOLVED`` / ``EXPIRED``) and the full
-    ``SessionMetadata``. The runtime emits an initial CREATED event for
-    every already-open session at subscribe time, then live events
-    thereafter — see ``runtime/src/server.rs::watch_sessions``.
+    string (``CREATED`` / ``RESOLVED`` / ``EXPIRED`` / ``CANCELLED`` /
+    ``SUSPENDED`` / ``RESUMED``) and the full ``SessionMetadata``. The
+    runtime emits an initial CREATED event for every already-open session at
+    subscribe time, then live events thereafter — see
+    ``runtime/src/server.rs::watch_sessions``.
     """
 
     def __init__(self, client: MacpClient, *, auth: AuthConfig | None = None) -> None:

{macp_sdk_python-0.3.0 → macp_sdk_python-0.4.0/src/macp_sdk_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: macp-sdk-python
-Version: 0.3.0
+Version: 0.4.0
 Summary: Python SDK for the MACP Rust runtime
 Author-email: OpenAI <support@openai.com>
 License: Apache-2.0
@@ -15,9 +15,9 @@ Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: grpcio>=1.74.0
+Requires-Dist: grpcio>=1.81.1
 Requires-Dist: protobuf>=5.27.0
-Requires-Dist: macp-proto<0.2.0,>=0.1.2
+Requires-Dist: macp-proto<0.2.0,>=0.1.3
 Provides-Extra: dev
 Requires-Dist: grpcio-tools>=1.74.0; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"
@@ -165,6 +165,7 @@ Business logic — voting rules, AI decision heuristics, policy enforcement —
 
 - `GetSession` returns metadata only (not mode state/transcript) — hence the local projection pattern; use `StreamSession` + `send_subscribe` for the full transcript
 - `StreamSession` is scoped to one session per stream; use `MacpStream.send_subscribe(session_id)` (RFC-MACP-0006-A1, since SDK 0.2.3 / `macp-proto 0.1.2`) to replay accepted history before live broadcast
-- For cross-session observability, use `MacpClient.list_sessions()` and `SessionLifecycleWatcher` (SDK 0.3.0) to enumerate active sessions and stream `CREATED` / `RESOLVED` / `EXPIRED` lifecycle events
+- For cross-session observability, use `MacpClient.list_sessions()` and `SessionLifecycleWatcher` (SDK 0.3.0) to enumerate active sessions and stream `CREATED` / `RESOLVED` / `EXPIRED` / `CANCELLED` / `SUSPENDED` / `RESUMED` lifecycle events
+- Pause and cancel sessions with `MacpClient.suspend_session()` / `resume_session()` / `cancel_session()` (SDK 0.4.0 / `macp-proto 0.1.3`). A suspended session is non-terminal and rejects messages until resumed; an accepted `cancel_session()` now terminates as `CANCELLED` (previously surfaced as `EXPIRED`)
 - `ListRoots` currently returns an empty list and `WatchRoots` idles — the runtime does not yet populate roots
 - Business policy (majority, quorum, veto) belongs in your orchestrator/policy layer

{macp_sdk_python-0.3.0 → macp_sdk_python-0.4.0}/src/macp_sdk_python.egg-info/requires.txt

@@ -1,6 +1,6 @@
-grpcio>=1.74.0
+grpcio>=1.81.1
 protobuf>=5.27.0
-macp-proto<0.2.0,>=0.1.2
+macp-proto<0.2.0,>=0.1.3
 
 [dev]
 grpcio-tools>=1.74.0