macp-sdk-python 0.4.1__tar.gz → 0.6.0__tar.gz

{macp_sdk_python-0.4.1/src/macp_sdk_python.egg-info → macp_sdk_python-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: macp-sdk-python
-Version: 0.4.1
+Version: 0.6.0
 Summary: Python SDK for the MACP Rust runtime
 Author-email: Multi-Agent Coordination Protocol <macp@multiagentcoordinationprotocol.org>
 License: Apache-2.0
@@ -20,18 +20,17 @@ Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: grpcio>=1.81.1
-Requires-Dist: protobuf>=5.27.0
-Requires-Dist: macp-proto<0.2.0,>=0.1.3
+Requires-Dist: grpcio>=1.82.0rc2
+Requires-Dist: protobuf>=7.35.0
+Requires-Dist: macp-proto<0.1.9,>=0.1.6
 Provides-Extra: dev
-Requires-Dist: grpcio-tools>=1.74.0; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"
-Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"
 Requires-Dist: mypy>=1.10; extra == "dev"
 Requires-Dist: ruff>=0.5; extra == "dev"
 Requires-Dist: grpc-stubs>=1.53; extra == "dev"
 Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: jsonschema>=4.0; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.5; extra == "docs"
 Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
@@ -131,9 +130,10 @@ make setup              # pip install -e ".[dev,docs]"
 make lint               # ruff check
 make fmt                # ruff format
 make typecheck          # mypy strict
-make test               # unit tests
+make test               # unit tests + coverage gate (85% branch, from pyproject)
+make test-integration   # integration tests (auto-skip without a running runtime)
 make test-all           # lint + typecheck + all tests
-make coverage           # coverage report
+make coverage           # HTML + terminal coverage report
 
 # Build
 make build              # sdist + wheel
@@ -149,6 +149,12 @@ export MACP_ALLOW_INSECURE=1
 cargo run   # in the runtime repo
 ```
 
+Since runtime **v0.5.0**, a runtime with no authentication configured
+(`MACP_AUTH_TOKENS_*` / `MACP_AUTH_ISSUER` unset) **refuses to start** unless
+`MACP_ALLOW_INSECURE=1` is set, and the published Docker image **no longer
+bakes that env in** — pass it explicitly for local dev (as above and in the
+`docker run` command in `CLAUDE.md`).
+
 Dev-agent auth rides the standard `Authorization: Bearer` header — the
 runtime's `dev_authenticate` fallback binds the token value verbatim
 as the sender.

{macp_sdk_python-0.4.1 → macp_sdk_python-0.6.0}/README.md

@@ -92,9 +92,10 @@ make setup              # pip install -e ".[dev,docs]"
 make lint               # ruff check
 make fmt                # ruff format
 make typecheck          # mypy strict
-make test               # unit tests
+make test               # unit tests + coverage gate (85% branch, from pyproject)
+make test-integration   # integration tests (auto-skip without a running runtime)
 make test-all           # lint + typecheck + all tests
-make coverage           # coverage report
+make coverage           # HTML + terminal coverage report
 
 # Build
 make build              # sdist + wheel
@@ -110,6 +111,12 @@ export MACP_ALLOW_INSECURE=1
 cargo run   # in the runtime repo
 ```
 
+Since runtime **v0.5.0**, a runtime with no authentication configured
+(`MACP_AUTH_TOKENS_*` / `MACP_AUTH_ISSUER` unset) **refuses to start** unless
+`MACP_ALLOW_INSECURE=1` is set, and the published Docker image **no longer
+bakes that env in** — pass it explicitly for local dev (as above and in the
+`docker run` command in `CLAUDE.md`).
+
 Dev-agent auth rides the standard `Authorization: Bearer` header — the
 runtime's `dev_authenticate` fallback binds the token value verbatim
 as the sender.

{macp_sdk_python-0.4.1 → macp_sdk_python-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "macp-sdk-python"
-version = "0.4.1"
+version = "0.6.0"
 description = "Python SDK for the MACP Rust runtime"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -23,18 +23,36 @@ classifiers = [
   "Topic :: Software Development :: Libraries",
 ]
 dependencies = [
-  # 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.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 context_id / extensions on SessionStartPayload.
-  # See docs/contributing.md "Bumping macp-proto".
-  "macp-proto>=0.1.3,<0.2.0",
+  # macp-proto 0.1.6's gencode was produced by protobuf 7.35.0 / grpc 1.82.0.
+  # protobuf enforces this at import time: importing macp.v1.core_pb2 under an
+  # older protobuf raises google.protobuf.runtime_version.VersionError
+  # ("runtime version cannot be older than the linked gencode version"), so
+  # these floors are hard requirements derived from the gencode, not from
+  # macp-proto's own (looser) METADATA. This is the consumer-visible bump in
+  # SDK 0.5.0 — deployments pinned to protobuf 6.x / grpcio < 1.82 cannot
+  # straddle it.
+  # grpcio 1.82.0 (stable) was YANKED from PyPI with no newer stable published
+  # yet, which made a ">=1.82.0" floor unsatisfiable in fresh environments
+  # (pip skips yanked versions when resolving ranges). The rc2 floor keeps the
+  # gencode's GRPC_GENERATED_VERSION=1.82.0 import check satisfied (verified:
+  # macp.v1.*_pb2_grpc imports cleanly under 1.82.0rc2) and, per PEP 440,
+  # a pre-release in the specifier lets pip resolve it; pip will prefer the
+  # next stable >= 1.82.1 as soon as one exists. Revisit then.
+  "grpcio>=1.82.0rc2",
+  "protobuf>=7.35.0",
+  # Requires 0.1.6+ for the runtime v0.5.0 wire surface referenced by the SDK:
+  # SessionStartPayload.max_suspend_ms (0.1.5), HandoffAcceptPayload.implicit
+  # and ListSessionsRequest.page_size/page_token (0.1.6), and the canonical
+  # macp.modes.multi_round.v1.ContributePayload proto encoding (0.1.4).
+  # Retains the 0.1.3 surface (suspend/cancel/supersede, subscribe_session_id/
+  # after_sequence, context_id/extensions). See docs/contributing.md
+  # "Bumping macp-proto".
+  # Capped below 0.1.8: that release's METADATA floor is "grpcio>=1.82.0",
+  # which is unsatisfiable while grpcio 1.82.0 stable is yanked (see the
+  # grpcio comment above) — PEP 440 sorts 1.82.0rc2 below 1.82.0, so no
+  # candidate exists. 0.1.6/0.1.7 declare "grpcio>=1.74.0" and resolve fine.
+  # Re-widen to <0.2.0 once grpcio publishes a stable >= 1.82.1.
+  "macp-proto>=0.1.6,<0.1.9",
 ]
 
 [project.urls]
@@ -45,15 +63,18 @@ Changelog = "https://github.com/multiagentcoordinationprotocol/macp-sdk-python/b
 "Bug Tracker" = "https://github.com/multiagentcoordinationprotocol/macp-sdk-python/issues"
 
 [project.optional-dependencies]
+# grpcio-tools was dropped from dev: this repo has no proto-generation step
+# (bindings come from the macp-proto package; generation lives in the spec
+# repo), and every installable grpcio-tools stable caps protobuf<7.0.0,
+# which conflicts with the protobuf>=7.35.0 floor above.
 dev = [
-  "grpcio-tools>=1.74.0",  # only needed for proto-python package publishing
   "pytest>=8.0",
-  "pytest-asyncio>=0.24",
   "pytest-cov>=5.0",
   "mypy>=1.10",
   "ruff>=0.5",
   "grpc-stubs>=1.53",
   "build>=1.0",
+  "jsonschema>=4.0",  # validate vendored conformance fixtures against schema.json
 ]
 docs = [
   "mkdocs-material>=9.5",
@@ -126,8 +147,27 @@ ignore_missing_imports = true
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
-asyncio_mode = "auto"
+addopts = "--strict-markers"
 markers = [
   "integration: requires running MACP runtime",
   "conformance: replays conformance fixtures against runtime",
 ]
+filterwarnings = [
+  "error",
+  # Unit tests build real MacpClient objects against localhost:0 with mocked
+  # stubs and rely on GC to reap the never-connected socket; the resulting
+  # "unclosed socket" ResourceWarning fires inside socket.__del__ and would
+  # otherwise escalate to PytestUnraisableExceptionWarning under -W error.
+  "ignore::ResourceWarning",
+]
+
+# Coverage gate: single source of truth for `make test`, `make coverage`, and
+# CI (all invoke pytest with a bare --cov and inherit source/branch/fail_under
+# from here).
+[tool.coverage.run]
+source = ["macp_sdk"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 85
+show_missing = true

{macp_sdk_python-0.4.1 → macp_sdk_python-0.6.0}/src/macp_sdk/__init__.py

@@ -20,6 +20,7 @@ from .decision import DecisionSession
 from .envelope import (
     build_commitment_payload,
     build_commitment_ref,
+    build_contribute_payload,
     build_envelope,
     build_progress_payload,
     build_root,
@@ -183,6 +184,7 @@ __all__ = [
     "VotingRules",
     "build_commitment_payload",
     "build_commitment_ref",
+    "build_contribute_payload",
     "build_decision_policy",
     "build_envelope",
     "build_handoff_policy",

{macp_sdk_python-0.4.1 → macp_sdk_python-0.6.0}/src/macp_sdk/agent/participant.py

@@ -69,6 +69,9 @@ class InitiatorConfig:
     mode_version: str | None = None
     configuration_version: str | None = None
     policy_version: str | None = None
+    # Runtime v0.5.0 per-session maximum-suspension cap (ms); 0 = runtime
+    # default (currently 7 days). Negative values are rejected at build time.
+    max_suspend_ms: int = 0
     kickoff_message_type: str | None = None
     kickoff_payload: dict[str, Any] = field(default_factory=dict)
 
@@ -113,8 +116,13 @@ class ParticipantActions:
         mode_version: str | None = None,
         configuration_version: str | None = None,
         policy_version: str | None = None,
+        max_suspend_ms: int = 0,
     ) -> Any:
-        """Send a SessionStart envelope to open the session."""
+        """Send a SessionStart envelope to open the session.
+
+        ``max_suspend_ms`` (runtime v0.5.0) binds a per-session maximum
+        suspension cap; ``0`` selects the runtime default.
+        """
         from ..constants import (
             DEFAULT_CONFIGURATION_VERSION,
             DEFAULT_MODE_VERSION,
@@ -135,6 +143,7 @@ class ParticipantActions:
             mode_version=mode_version or DEFAULT_MODE_VERSION,
             configuration_version=configuration_version or DEFAULT_CONFIGURATION_VERSION,
             policy_version=policy_version or DEFAULT_POLICY_VERSION,
+            max_suspend_ms=max_suspend_ms,
         )
         envelope = build_envelope(
             mode=self._mode,
@@ -522,6 +531,7 @@ class Participant:
             mode_version=cfg.mode_version,
             configuration_version=cfg.configuration_version,
             policy_version=cfg.policy_version,
+            max_suspend_ms=cfg.max_suspend_ms,
         )
         logger.info("SessionStart emitted (session=%s)", self._session_id)
 

{macp_sdk_python-0.4.1 → macp_sdk_python-0.6.0}/src/macp_sdk/agent/runner.py

@@ -123,6 +123,11 @@ def from_bootstrap(bootstrap_path: str | None = None) -> Participant:
             intent=str(ss.get("intent", "")),
             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.
+            max_suspend_ms=int(ss.get("max_suspend_ms", 0)),
             context_id=str(ss.get("context_id", "")),
             extensions=_decode_extensions(ss.get("extensions")),
             roots=ss.get("roots"),

{macp_sdk_python-0.4.1 → macp_sdk_python-0.6.0}/src/macp_sdk/base_session.py

@@ -102,10 +102,17 @@ class BaseSession(ABC):
         context_id: str = "",
         extensions: Mapping[str, bytes] | None = None,
         roots: Iterable[Any] | None = None,
+        max_suspend_ms: int = 0,
         sender: str | None = None,
         auth: AuthConfig | None = None,
     ) -> envelope_pb2.Ack:
-        """Send SessionStart and begin tracking via the projection."""
+        """Send SessionStart and begin tracking via the projection.
+
+        ``max_suspend_ms`` (runtime v0.5.0) binds a per-session maximum
+        suspension cap; ``0`` selects the runtime default (currently 7 days).
+        A suspension outlasting this cap expires the session
+        (``SUSPENDED`` → ``EXPIRED``). Negative values are rejected.
+        """
         validate_participant_count(len(participants))
         payload = build_session_start_payload(
             intent=intent,
@@ -117,6 +124,7 @@ class BaseSession(ABC):
             context_id=context_id,
             extensions=extensions,
             roots=roots,
+            max_suspend_ms=max_suspend_ms,
         )
         envelope = build_envelope(
             mode=self.MODE,
@@ -138,7 +146,16 @@ class BaseSession(ABC):
         sender: str | None = None,
         auth: AuthConfig | None = None,
     ) -> envelope_pb2.Ack:
-        """Send Commitment to resolve the session."""
+        """Send Commitment to resolve the session.
+
+        The commitment echoes ``self.policy_version``. Runtime v0.5.0 relaxed
+        the match rule (RFC-MACP-0012, change review A3): an **empty**
+        ``policy_version`` matches whatever policy the session is bound to, so
+        a session started with an empty policy_version no longer has to echo
+        ``policy.default``. A **non-empty** value must still equal the
+        resolved policy id (e.g. ``policy.default``) or the commitment is
+        rejected with ``UNKNOWN_POLICY_VERSION``.
+        """
         payload = build_commitment_payload(
             action=action,
             authority_scope=authority_scope,

{macp_sdk_python-0.4.1 → macp_sdk_python-0.6.0}/src/macp_sdk/client.py

@@ -21,6 +21,7 @@ from .errors import (
     MacpAckError,
     MacpIdentityMismatchError,
     MacpSdkError,
+    MacpSessionError,
     MacpTransportError,
 )
 
@@ -69,6 +70,33 @@ def _parse_grpc_metadata_reasons(rpc_error: grpc.RpcError) -> list[str]:
     return []
 
 
+def _rpc_status_name(rpc_err: grpc.RpcError) -> str | None:
+    """Return the gRPC status code name for *rpc_err*, or None.
+
+    Defensive against error objects that don't implement ``code()`` (the bare
+    ``grpc.RpcError`` base class doesn't; only concrete call errors do).
+    """
+    code_fn = getattr(rpc_err, "code", None)
+    if not callable(code_fn):
+        return None
+    try:
+        status = code_fn()
+    except Exception:
+        return None
+    return status.name if status is not None else None
+
+
+def _rpc_details(rpc_err: grpc.RpcError) -> str | None:
+    """Return ``rpc_err.details()`` if available, else None."""
+    details_fn = getattr(rpc_err, "details", None)
+    if not callable(details_fn):
+        return None
+    try:
+        return details_fn()
+    except Exception:
+        return None
+
+
 def _default_capabilities() -> core_pb2.Capabilities:
     return core_pb2.Capabilities(
         sessions=core_pb2.SessionsCapability(stream=True, list_sessions=True, watch_sessions=True),
@@ -159,8 +187,18 @@ class MacpStream:
 
     def send_subscribe(self, session_id: str, after_sequence: int = 0) -> None:
         """RFC-MACP-0006-A1: Send a subscribe-only frame to receive session
-        history + live broadcast. The runtime replays accepted envelopes from
-        ``after_sequence`` onwards, then continues with live broadcast.
+        history + live broadcast.
+
+        ``after_sequence`` (RFC-MACP-0006 §3.2, runtime v0.5.0) is the 1-based
+        ordinal over *accepted envelopes*, interpreted **exclusively**: ``0``
+        (default) replays from the start; ``N`` replays from envelope ``N+1``
+        onward, so envelope ``N`` is never re-delivered. Ordinals are
+        contiguous and stable across log compaction and runtime restart. To
+        resume, track how many envelopes you have consumed and pass that count
+        as ``after_sequence`` on reconnect. Resuming below a compacted range
+        fails the stream with gRPC ``FAILED_PRECONDITION`` (surfaced as
+        ``MacpTransportError(code="FAILED_PRECONDITION")`` from :meth:`read`) —
+        restart from ``0`` and reconcile.
         """
         if self._closed:
             raise MacpSdkError("stream is already closed")
@@ -175,7 +213,10 @@ class MacpStream:
         if item is self._END:
             return None
         if isinstance(item, grpc.RpcError):
-            raise MacpTransportError(item.details() or str(item))
+            raise MacpTransportError(
+                _rpc_details(item) or str(item),
+                code=_rpc_status_name(item),
+            )
         assert isinstance(item, envelope_pb2.Envelope)
         return item
 
@@ -213,7 +254,7 @@ class MacpClient:
         root_certificates: bytes | None = None,
         default_timeout: float | None = None,
         client_name: str = "macp-sdk-python",
-        client_version: str = "0.4.0",
+        client_version: str = "0.5.0",
     ) -> None:
         if secure is None:
             secure = not allow_insecure
@@ -256,6 +297,43 @@ class MacpClient:
             raise MacpSdkError("this operation requires auth; pass auth= or configure client.auth")
         return selected
 
+    @staticmethod
+    def _transport_error_from_rpc(rpc_err: grpc.RpcError) -> MacpTransportError:
+        """Build a :class:`MacpTransportError` preserving the gRPC status code.
+
+        Watch/stream RPCs surface consumer lag as ``RESOURCE_EXHAUSTED`` and a
+        missing-auth ``WatchSignals`` as ``UNAUTHENTICATED``; attaching the
+        code lets callers decide to reconnect (lag) vs. fix auth vs. give up.
+        """
+        return MacpTransportError(
+            _rpc_details(rpc_err) or str(rpc_err),
+            code=_rpc_status_name(rpc_err),
+        )
+
+    @staticmethod
+    def _map_registry_mutation_error(rpc_err: grpc.RpcError, *, read_only_hint: str) -> Exception:
+        """Translate a registry-mutation ``RpcError`` into a typed SDK error.
+
+        A runtime configured with a read-only registry (e.g.
+        ``MACP_POLICIES_DIR`` for policies) advertises the corresponding
+        capability as ``false`` in ``Initialize`` and rejects every mutating
+        RPC with gRPC ``FAILED_PRECONDITION``. Surface that as a
+        :class:`MacpAckError` carrying the code so callers can branch on it,
+        mirroring how ``send``/``cancel_session`` surface NACKs. Any other
+        status stays a :class:`MacpTransportError` with the code attached.
+        """
+        name = _rpc_status_name(rpc_err)
+        if name == "FAILED_PRECONDITION":
+            failure = AckFailure(
+                code="FAILED_PRECONDITION",
+                message=_rpc_details(rpc_err) or read_only_hint,
+            )
+            return MacpAckError(failure)
+        return MacpTransportError(
+            _rpc_details(rpc_err) or str(rpc_err),
+            code=name,
+        )
+
     @staticmethod
     def _resolve_sender(auth_cfg: AuthConfig, sender: str) -> str:
         """Resolve and validate the envelope sender against auth.expected_sender.
@@ -418,6 +496,12 @@ class MacpClient:
         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``.
+
+        A suspension that outlasts the session-bound ``max_suspend_ms`` cap
+        (set at ``SessionStart``; runtime v0.5.0) expires the session
+        (``SUSPENDED`` → ``EXPIRED``), observed as an ``EVENT_TYPE_EXPIRED``
+        lifecycle event. ``max_suspend_ms=0`` uses the runtime default
+        (currently 7 days).
         """
         auth_cfg = self._require_auth(auth)
         try:
@@ -491,23 +575,55 @@ class MacpClient:
     def list_sessions(
         self,
         *,
+        page_size: int = 0,
         auth: AuthConfig | None = None,
         timeout: float | None = None,
     ) -> list[core_pb2.SessionMetadata]:
         """List all active sessions known to the runtime.
 
-        Returns the populated ``sessions`` repeated field of
-        ``ListSessionsResponse`` as a plain ``list`` so callers don't have
-        to reach through the proto wrapper. Per runtime semantics each
-        entry includes ``context_id`` and ``extension_keys``.
+        Auto-paginates (macp-proto >= 0.1.6 / runtime v0.5.0): repeatedly
+        requests ``ListSessions`` with the runtime's ``next_page_token`` until
+        it is empty, so the returned ``list`` is always the *complete* set
+        regardless of the runtime's page size. Each entry includes
+        ``context_id`` and ``extension_keys``. ``page_size`` (0 = server
+        default) tunes the per-request batch. Use :meth:`list_sessions_page`
+        for manual, single-page control.
+        """
+        auth_cfg = self._require_auth(auth)
+        sessions: list[core_pb2.SessionMetadata] = []
+        page_token = ""
+        while True:
+            batch, page_token = self.list_sessions_page(
+                page_size=page_size,
+                page_token=page_token,
+                auth=auth_cfg,
+                timeout=timeout,
+            )
+            sessions.extend(batch)
+            if not page_token:
+                return sessions
+
+    def list_sessions_page(
+        self,
+        *,
+        page_size: int = 0,
+        page_token: str = "",
+        auth: AuthConfig | None = None,
+        timeout: float | None = None,
+    ) -> tuple[list[core_pb2.SessionMetadata], str]:
+        """Fetch a single page of sessions (macp-proto >= 0.1.6).
+
+        Returns ``(sessions, next_page_token)``. An empty ``next_page_token``
+        means the last page. Callers that want to drain all pages should use
+        :meth:`list_sessions`, which loops this for them.
         """
         auth_cfg = self._require_auth(auth)
         resp = self.stub.ListSessions(
-            core_pb2.ListSessionsRequest(),
+            core_pb2.ListSessionsRequest(page_size=page_size, page_token=page_token),
             metadata=self._metadata(auth_cfg),
             timeout=timeout or self.default_timeout,
         )
-        return list(resp.sessions)
+        return list(resp.sessions), resp.next_page_token
 
     def watch_sessions(
         self,
@@ -535,7 +651,7 @@ class MacpClient:
         try:
             yield from call
         except grpc.RpcError as exc:
-            raise MacpTransportError(str(exc)) from exc
+            raise self._transport_error_from_rpc(exc) from exc
 
     def register_ext_mode(
         self,
@@ -544,12 +660,37 @@ class MacpClient:
         auth: AuthConfig | None = None,
         timeout: float | None = None,
     ) -> core_pb2.RegisterExtModeResponse:
+        """Register an extension-mode descriptor with the runtime.
+
+        Descriptors must declare ``Commitment`` among their
+        ``terminal_message_types`` (runtime v0.5.0 rejects those that don't),
+        and an ext session started without ``mode_version`` binds the
+        registered descriptor's version. Against a read-only mode registry the
+        runtime rejects this with gRPC ``FAILED_PRECONDITION``, surfaced here
+        as :class:`MacpAckError`.
+
+        Raises :class:`MacpSessionError` client-side if the descriptor omits
+        ``Commitment`` from ``terminal_message_types`` (runtime v0.5.0 requires
+        it), giving a clearer error than the runtime's rejection.
+        """
+        if "Commitment" not in descriptor.terminal_message_types:
+            raise MacpSessionError(
+                "ext-mode descriptor must declare 'Commitment' in "
+                "terminal_message_types (runtime v0.5.0 rejects descriptors "
+                "without a Commitment terminal type)"
+            )
         auth_cfg = self._require_auth(auth)
-        return self.stub.RegisterExtMode(
-            core_pb2.RegisterExtModeRequest(mode_descriptor=descriptor),
-            metadata=self._metadata(auth_cfg),
-            timeout=timeout or self.default_timeout,
-        )
+        try:
+            return self.stub.RegisterExtMode(
+                core_pb2.RegisterExtModeRequest(mode_descriptor=descriptor),
+                metadata=self._metadata(auth_cfg),
+                timeout=timeout or self.default_timeout,
+            )
+        except grpc.RpcError as rpc_err:
+            raise self._map_registry_mutation_error(
+                rpc_err,
+                read_only_hint="RegisterExtMode refused: the mode registry is read-only",
+            ) from rpc_err
 
     def unregister_ext_mode(
         self,
@@ -559,11 +700,17 @@ class MacpClient:
         timeout: float | None = None,
     ) -> core_pb2.UnregisterExtModeResponse:
         auth_cfg = self._require_auth(auth)
-        return self.stub.UnregisterExtMode(
-            core_pb2.UnregisterExtModeRequest(mode=mode),
-            metadata=self._metadata(auth_cfg),
-            timeout=timeout or self.default_timeout,
-        )
+        try:
+            return self.stub.UnregisterExtMode(
+                core_pb2.UnregisterExtModeRequest(mode=mode),
+                metadata=self._metadata(auth_cfg),
+                timeout=timeout or self.default_timeout,
+            )
+        except grpc.RpcError as rpc_err:
+            raise self._map_registry_mutation_error(
+                rpc_err,
+                read_only_hint="UnregisterExtMode refused: the mode registry is read-only",
+            ) from rpc_err
 
     def promote_mode(
         self,
@@ -573,12 +720,25 @@ class MacpClient:
         auth: AuthConfig | None = None,
         timeout: float | None = None,
     ) -> core_pb2.PromoteModeResponse:
+        """Promote a registered extension mode to a first-class mode.
+
+        Runtime v0.5.0 rejects promotion into the reserved ``macp.mode.*``
+        namespace. Against a read-only mode registry the runtime rejects this
+        with gRPC ``FAILED_PRECONDITION``, surfaced here as
+        :class:`MacpAckError`.
+        """
         auth_cfg = self._require_auth(auth)
-        return self.stub.PromoteMode(
-            core_pb2.PromoteModeRequest(mode=mode, promoted_mode_name=promoted_mode_name),
-            metadata=self._metadata(auth_cfg),
-            timeout=timeout or self.default_timeout,
-        )
+        try:
+            return self.stub.PromoteMode(
+                core_pb2.PromoteModeRequest(mode=mode, promoted_mode_name=promoted_mode_name),
+                metadata=self._metadata(auth_cfg),
+                timeout=timeout or self.default_timeout,
+            )
+        except grpc.RpcError as rpc_err:
+            raise self._map_registry_mutation_error(
+                rpc_err,
+                read_only_hint="PromoteMode refused: the mode registry is read-only",
+            ) from rpc_err
 
     # ── Governance policy lifecycle ───────────────────────────────────
 
@@ -589,13 +749,28 @@ class MacpClient:
         auth: AuthConfig | None = None,
         timeout: float | None = None,
     ) -> policy_pb2.RegisterPolicyResponse:
-        """Register a governance policy with the runtime."""
+        """Register a governance policy with the runtime.
+
+        Raises :class:`MacpAckError` with ``code="FAILED_PRECONDITION"`` when
+        the runtime's policy registry is read-only — a runtime started with
+        ``MACP_POLICIES_DIR`` advertises ``policy_registry.register_policy:
+        false`` in :meth:`initialize` and refuses all mutating policy RPCs.
+        Check that capability before registering to avoid the round-trip.
+        """
         auth_cfg = self._require_auth(auth)
-        return self.stub.RegisterPolicy(
-            policy_pb2.RegisterPolicyRequest(policy_descriptor=descriptor),
-            metadata=self._metadata(auth_cfg),
-            timeout=timeout or self.default_timeout,
-        )
+        try:
+            return self.stub.RegisterPolicy(
+                policy_pb2.RegisterPolicyRequest(policy_descriptor=descriptor),
+                metadata=self._metadata(auth_cfg),
+                timeout=timeout or self.default_timeout,
+            )
+        except grpc.RpcError as rpc_err:
+            raise self._map_registry_mutation_error(
+                rpc_err,
+                read_only_hint="RegisterPolicy refused: the policy registry is read-only "
+                "(runtime configured with MACP_POLICIES_DIR; "
+                "Initialize advertises policy_registry.register_policy=false)",
+            ) from rpc_err
 
     def unregister_policy(
         self,
@@ -604,13 +779,24 @@ class MacpClient:
         auth: AuthConfig | None = None,
         timeout: float | None = None,
     ) -> policy_pb2.UnregisterPolicyResponse:
-        """Unregister a governance policy from the runtime."""
+        """Unregister a governance policy from the runtime.
+
+        Like :meth:`register_policy`, raises :class:`MacpAckError` with
+        ``code="FAILED_PRECONDITION"`` against a read-only registry.
+        """
         auth_cfg = self._require_auth(auth)
-        return self.stub.UnregisterPolicy(
-            policy_pb2.UnregisterPolicyRequest(policy_id=policy_id),
-            metadata=self._metadata(auth_cfg),
-            timeout=timeout or self.default_timeout,
-        )
+        try:
+            return self.stub.UnregisterPolicy(
+                policy_pb2.UnregisterPolicyRequest(policy_id=policy_id),
+                metadata=self._metadata(auth_cfg),
+                timeout=timeout or self.default_timeout,
+            )
+        except grpc.RpcError as rpc_err:
+            raise self._map_registry_mutation_error(
+                rpc_err,
+                read_only_hint="UnregisterPolicy refused: the policy registry is read-only "
+                "(runtime configured with MACP_POLICIES_DIR)",
+            ) from rpc_err
 
     def get_policy(
         self,
@@ -643,18 +829,24 @@ class MacpClient:
         )
 
     def watch_policies(
-        self, *, timeout: float | None = None
+        self, *, auth: AuthConfig | None = None, timeout: float | None = None
     ) -> Iterator[policy_pb2.WatchPoliciesResponse]:
-        """Server-streaming RPC: yields governance policy change events."""
+        """Server-streaming RPC: yields governance policy change events.
+
+        Auth is forwarded when available (``auth`` arg or ``client.auth``) but
+        not required. A lagging consumer is terminated with
+        ``RESOURCE_EXHAUSTED``; reconnect to resume.
+        """
         logger.debug("watch_policies starting")
         call = self.stub.WatchPolicies(
             policy_pb2.WatchPoliciesRequest(),
+            metadata=self._metadata(auth),
             timeout=timeout or self.default_timeout,
         )
         try:
             yield from call
         except grpc.RpcError as exc:
-            raise MacpTransportError(str(exc)) from exc
+            raise self._transport_error_from_rpc(exc) from exc
 
     def open_stream(
         self, *, auth: AuthConfig | None = None, timeout: float | None = None
@@ -667,44 +859,64 @@ class MacpClient:
         )
 
     def watch_mode_registry(
-        self, *, timeout: float | None = None
+        self, *, auth: AuthConfig | None = None, timeout: float | None = None
     ) -> Iterator[core_pb2.WatchModeRegistryResponse]:
-        """Server-streaming RPC: yields mode registry change events."""
+        """Server-streaming RPC: yields mode registry change events.
+
+        Auth is forwarded when available but not required.
+        """
         logger.debug("watch_mode_registry starting")
         call = self.stub.WatchModeRegistry(
             core_pb2.WatchModeRegistryRequest(),
+            metadata=self._metadata(auth),
             timeout=timeout or self.default_timeout,
         )
         try:
             yield from call
         except grpc.RpcError as exc:
-            raise MacpTransportError(str(exc)) from exc
+            raise self._transport_error_from_rpc(exc) from exc
 
-    def watch_roots(self, *, timeout: float | None = None) -> Iterator[core_pb2.WatchRootsResponse]:
-        """Server-streaming RPC: yields root change events."""
+    def watch_roots(
+        self, *, auth: AuthConfig | None = None, timeout: float | None = None
+    ) -> Iterator[core_pb2.WatchRootsResponse]:
+        """Server-streaming RPC: yields root change events.
+
+        The runtime advertises ``roots.list_changed: false`` and does not yet
+        populate roots, so this stream idles. Auth is forwarded when available
+        but not required.
+        """
         logger.debug("watch_roots starting")
         call = self.stub.WatchRoots(
             core_pb2.WatchRootsRequest(),
+            metadata=self._metadata(auth),
             timeout=timeout or self.default_timeout,
         )
         try:
             yield from call
         except grpc.RpcError as exc:
-            raise MacpTransportError(str(exc)) from exc
+            raise self._transport_error_from_rpc(exc) from exc
 
     def watch_signals(
-        self, *, timeout: float | None = None
+        self, *, auth: AuthConfig | None = None, timeout: float | None = None
     ) -> Iterator[core_pb2.WatchSignalsResponse]:
-        """Server-streaming RPC: yields ambient signal envelopes."""
+        """Server-streaming RPC: yields ambient signal envelopes.
+
+        Requires authentication since runtime v0.5.0 — an unauthenticated
+        ``WatchSignals`` is rejected with gRPC ``UNAUTHENTICATED`` (surfaced
+        as ``MacpTransportError(code="UNAUTHENTICATED")``). A lagging consumer
+        is terminated with ``RESOURCE_EXHAUSTED``; reconnect to resume.
+        """
         logger.debug("watch_signals starting")
+        auth_cfg = self._require_auth(auth)
         call = self.stub.WatchSignals(
             core_pb2.WatchSignalsRequest(),
+            metadata=self._metadata(auth_cfg),
             timeout=timeout or self.default_timeout,
         )
         try:
             yield from call
         except grpc.RpcError as exc:
-            raise MacpTransportError(str(exc)) from exc
+            raise self._transport_error_from_rpc(exc) from exc
 
     def send_signal(
         self,

{macp_sdk_python-0.4.1 → macp_sdk_python-0.6.0}/src/macp_sdk/envelope.py

@@ -4,6 +4,7 @@ import time
 import uuid
 from collections.abc import Iterable, Mapping, Sequence
 
+from macp.modes.multi_round.v1 import multi_round_pb2
 from macp.v1 import core_pb2, envelope_pb2
 
 from .constants import (
@@ -50,6 +51,11 @@ def build_root(uri: str, name: str = "") -> core_pb2.Root:
     return core_pb2.Root(uri=uri, name=name)
 
 
+def _has_max_suspend_ms_field() -> bool:
+    """Check if the proto schema supports SessionStartPayload.max_suspend_ms (>=0.1.5)."""
+    return any(f.name == "max_suspend_ms" for f in core_pb2.SessionStartPayload.DESCRIPTOR.fields)
+
+
 def build_session_start_payload(
     *,
     intent: str,
@@ -61,8 +67,22 @@ def build_session_start_payload(
     context_id: str = "",
     extensions: Mapping[str, bytes] | None = None,
     roots: Iterable[core_pb2.Root] | None = None,
+    max_suspend_ms: int = 0,
 ) -> core_pb2.SessionStartPayload:
-    return core_pb2.SessionStartPayload(
+    """Build a ``SessionStartPayload``.
+
+    ``max_suspend_ms`` (macp-proto >= 0.1.5, runtime v0.5.0) binds a
+    per-session maximum-suspension cap at start. ``0`` (the default) or an
+    absent field selects the runtime default (currently 7 days). The runtime
+    rejects negative values at ``SessionStart``, so they are rejected
+    client-side here with a clear message. proto3 does not serialize a scalar
+    ``0``, so the default keeps byte-compatibility with pre-0.1.5 payloads.
+    """
+    if max_suspend_ms < 0:
+        raise MacpSessionError(
+            f"max_suspend_ms must be >= 0 (0 selects the runtime default), got {max_suspend_ms}"
+        )
+    kwargs: dict[str, object] = dict(
         intent=intent,
         participants=list(participants),
         mode_version=mode_version,
@@ -73,6 +93,9 @@ def build_session_start_payload(
         extensions=dict(extensions) if extensions else {},
         roots=list(roots or []),
     )
+    if max_suspend_ms and _has_max_suspend_ms_field():
+        kwargs["max_suspend_ms"] = max_suspend_ms
+    return core_pb2.SessionStartPayload(**kwargs)
 
 
 def _has_outcome_positive_field() -> bool:
@@ -164,6 +187,17 @@ def build_progress_payload(
     )
 
 
+def build_contribute_payload(value: str) -> multi_round_pb2.ContributePayload:
+    """Build a ``ContributePayload`` for the ``ext.multi_round.v1`` mode.
+
+    Runtime v0.5.0 / macp-proto >= 0.1.4 moved Contribute onto the canonical
+    protobuf wire format. The runtime still permanently accepts legacy JSON
+    (``{"value": "..."}``) — see ``ProtoRegistry.decode_known_payload`` — but
+    new clients should emit proto via this builder.
+    """
+    return multi_round_pb2.ContributePayload(value=value)
+
+
 def serialize_message(message: object) -> bytes:
     serializer = getattr(message, "SerializeToString", None)
     if serializer is None:

{macp_sdk_python-0.4.1 → macp_sdk_python-0.6.0}/src/macp_sdk/errors.py

@@ -69,7 +69,19 @@ class MacpAckError(MacpSdkError):
 
 
 class MacpTransportError(MacpSdkError):
-    """gRPC communication failure."""
+    """gRPC communication failure.
+
+    ``code`` carries the gRPC status code name (e.g. ``"RESOURCE_EXHAUSTED"``,
+    ``"UNAUTHENTICATED"``, ``"FAILED_PRECONDITION"``) when the failure
+    originated from an ``RpcError``, or ``None`` otherwise. It lets callers
+    distinguish a lagging watch/stream consumer (``RESOURCE_EXHAUSTED`` →
+    reconnect) or a missing-auth watch (``UNAUTHENTICATED``) from a generic
+    transport failure without parsing the message string.
+    """
+
+    def __init__(self, message: str, *, code: str | None = None) -> None:
+        self.code = code
+        super().__init__(message)
 
 
 class MacpSessionError(MacpSdkError):

{macp_sdk_python-0.4.1 → macp_sdk_python-0.6.0}/src/macp_sdk/handoff.py

@@ -27,6 +27,12 @@ class HandoffRecord:
     context_content_type: str | None
     accepted_by: str | None
     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 v0.5.0 defines but does not yet emit these; the SDK surfaces the
+    # field so histories that contain them replay correctly. Client-submitted
+    # accepts are always ``implicit=False`` (the runtime rejects a forged True).
+    implicit: bool = False
 
 
 # ---------------------------------------------------------------------------
@@ -83,6 +89,12 @@ class HandoffProjection(BaseProjection):
             if handoff is not None:
                 handoff.status = "accepted"
                 handoff.accepted_by = p.accepted_by
+                # macp-proto >= 0.1.6: capture whether this was a runtime
+                # implicit accept (sender = target, message_id
+                # ``implicit-accept:<handoff_id>``). Absent field decodes to
+                # False. If ``handoff`` is None the offer was never observed
+                # (e.g. mid-session subscribe) — we still advance the phase.
+                handoff.implicit = getattr(p, "implicit", False)
             self.phase = "Accepted"
             return
 
@@ -119,6 +131,18 @@ class HandoffProjection(BaseProjection):
         handoff = self.handoffs.get(handoff_id)
         return handoff is not None and handoff.status == "declined"
 
+    def is_implicitly_accepted(self, handoff_id: str) -> bool:
+        """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 v0.5.0 does not yet
+        emit implicit accepts, so this returns False for all live sessions
+        today; it exists so histories/replays that carry them surface the
+        distinction.
+        """
+        handoff = self.handoffs.get(handoff_id)
+        return handoff is not None and handoff.status == "accepted" and handoff.implicit
+
     def get_handoff(self, handoff_id: str) -> HandoffRecord | None:
         """Return the handoff record for *handoff_id*, or None."""
         return self.handoffs.get(handoff_id)
@@ -203,6 +227,11 @@ class HandoffSession(BaseSession):
         sender: str | None = None,
         auth: AuthConfig | None = None,
     ) -> envelope_pb2.Ack:
+        # Deliberately no ``implicit`` parameter: RFC-MACP-0010 §5.1 reserves
+        # ``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.
         payload = handoff_pb2.HandoffAcceptPayload(
             handoff_id=handoff_id,
             accepted_by=accepted_by or self._sender_for(sender, auth=auth),

{macp_sdk_python-0.4.1 → macp_sdk_python-0.6.0}/src/macp_sdk/policy.py

@@ -12,6 +12,8 @@ from dataclasses import dataclass, field
 
 from macp.v1 import policy_pb2
 
+from .errors import MacpSessionError
+
 # ── Shared commitment rules (all modes) ─────────────────────────────
 
 
@@ -145,10 +147,19 @@ def build_decision_policy(
 
 @dataclass(frozen=True, slots=True)
 class QuorumThreshold:
-    """Quorum threshold configuration (RFC: ``threshold`` object)."""
+    """Quorum threshold configuration (RFC-MACP-0012 §4.2 ``threshold`` object).
+
+    ``threshold`` is strictly the **approval bar** — the number/percentage of
+    approvals required to commit. There is no separate participation quorum in
+    schema_version <= 2. ``value`` is an **integer** in the canonical
+    ``quorum-rules.schema.json``: an approval count for ``n_of_m`` /
+    ``weighted``, and an integer percentage 0-100 for ``percentage``. A
+    fractional value (e.g. ``0.75``) is rejected by the runtime's schema
+    validation, so this is typed ``int`` and range-checked at build time.
+    """
 
     type: str = "n_of_m"
-    value: float = 0
+    value: int = 0
 
 
 @dataclass(frozen=True, slots=True)
@@ -172,6 +183,16 @@ def build_quorum_policy(
     a = abstention or AbstentionRules()
     c = commitment or CommitmentRules()
 
+    # Match the canonical schema's constraints before the runtime does, so a
+    # bad descriptor fails immediately client-side instead of round-tripping
+    # to an INVALID_POLICY_DEFINITION from RegisterPolicy.
+    if t.value < 0:
+        raise MacpSessionError(f"quorum threshold value must be >= 0, got {t.value}")
+    if t.type == "percentage" and t.value > 100:
+        raise MacpSessionError(
+            f"quorum threshold value must be 0-100 for type 'percentage', got {t.value}"
+        )
+
     rules: dict[str, object] = {
         "threshold": {"type": t.type, "value": t.value},
         "abstention": {

{macp_sdk_python-0.4.1 → macp_sdk_python-0.6.0}/src/macp_sdk/proto_registry.py

@@ -66,7 +66,11 @@ MODE_MAP: dict[str, dict[str, str]] = {
         "Abstain": "macp.modes.quorum.v1.AbstainPayload",
     },
     MODE_MULTI_ROUND: {
-        "Contribute": "__json__",
+        # Runtime v0.5.0 / macp-proto >= 0.1.4: Contribute is the last
+        # advertised mode moved onto the canonical protobuf wire format.
+        # Legacy JSON (``{"value": "..."}``) is still decoded (tried first,
+        # permanently) — see ``decode_known_payload``.
+        "Contribute": "macp.modes.multi_round.v1.ContributePayload",
     },
 }
 
@@ -88,6 +92,7 @@ def _ensure_pb2_imports() -> None:
         "macp.modes.task.v1.task_pb2",
         "macp.modes.handoff.v1.handoff_pb2",
         "macp.modes.quorum.v1.quorum_pb2",
+        "macp.modes.multi_round.v1.multi_round_pb2",
     ):
         importlib.import_module(_mod)
     _PB2_MODULES_LOADED = True
@@ -133,8 +138,29 @@ class ProtoRegistry:
         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)
+        if mode == MODE_MULTI_ROUND and message_type == "Contribute":
+            # RFC-MACP contract: multi_round Contribute accepts legacy JSON
+            # (``{"value": "..."}``) *permanently* and tries it first, so
+            # pre-proto histories/replays decode byte-identically. Proto
+            # (``ContributePayload``) is the new canonical encoding; its
+            # serialized bytes are not valid JSON, so the JSON attempt fails
+            # loudly and we fall through to proto.
+            return self._decode_json_first_then_proto(type_name, payload)
         return self.decode_message(type_name, payload)
 
+    def _decode_json_first_then_proto(
+        self, type_name: str, payload: bytes
+    ) -> dict[str, Any] | None:
+        if not payload:
+            return None
+        try:
+            parsed = json.loads(payload.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError, ValueError):
+            return self.decode_message(type_name, payload)
+        # Legacy JSON payload — keep the ``{"encoding": "json", "json": ...}``
+        # shape that existing consumers of decoded dicts already handle.
+        return {"encoding": "json", "json": parsed}
+
     @staticmethod
     def _try_decode_utf8(payload: bytes) -> dict[str, Any] | None:
         if not payload:

{macp_sdk_python-0.4.1 → macp_sdk_python-0.6.0}/src/macp_sdk/validation.py

@@ -10,7 +10,15 @@ from collections.abc import Sequence
 
 from .errors import MacpSessionError
 
-_UUID_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$")
+# A string with the structural shape of a UUID (36 chars, hyphens at
+# 8-13-18-23, hex-only otherwise) — case-insensitive, any version/variant.
+_UUID_SHAPE_RE = re.compile(
+    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+)
+# Strict lowercase UUID v4/v7 (version nibble 4 or 7, RFC 9562 variant 8/9/a/b).
+_UUID_V4V7_RE = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-[47][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+)
 _BASE64URL_RE = re.compile(r"^[A-Za-z0-9_-]{22,}$")
 
 _VALID_VOTES = frozenset({"APPROVE", "REJECT", "ABSTAIN"})
@@ -22,11 +30,31 @@ _MAX_TTL_MS = 86_400_000  # 24 hours
 
 
 def validate_session_id(sid: str) -> None:
-    """Validate that *sid* matches UUID v4/v7 or base64url (22+ chars)."""
-    if not (_UUID_RE.match(sid) or _BASE64URL_RE.match(sid)):
-        raise MacpSessionError(
-            f"session_id must be UUID v4/v7 or base64url (22+ chars), got: {sid!r}"
-        )
+    """Validate that *sid* is a lowercase UUID v4/v7 or base64url (22+ chars).
+
+    Mirrors the runtime's **no-fall-through** rule (runtime v0.5.0 change
+    review A4): a string that has the structural shape of a UUID is validated
+    strictly as a lowercase v4/v7 UUID — it is *not* reinterpreted as
+    base64url (which would otherwise accept an uppercase or wrong-version
+    UUID). A 36-char base64url ID containing ``-`` that is not UUID-shaped
+    (e.g. non-hex characters) still validates via the base64url branch, as the
+    runtime accepts.
+
+    This validation is advisory — it runs only when an explicit ``session_id``
+    is passed; auto-generated IDs are always valid v4 UUIDs.
+    """
+    if _UUID_SHAPE_RE.match(sid):
+        if not _UUID_V4V7_RE.match(sid):
+            raise MacpSessionError(
+                "session_id is UUID-shaped but not a lowercase v4/v7 UUID "
+                f"(no fall-through to base64url), got: {sid!r}"
+            )
+        return
+    if _BASE64URL_RE.match(sid):
+        return
+    raise MacpSessionError(
+        f"session_id must be a lowercase UUID v4/v7 or base64url (22+ chars), got: {sid!r}"
+    )
 
 
 def validate_vote(value: str) -> str:

{macp_sdk_python-0.4.1 → macp_sdk_python-0.6.0}/src/macp_sdk/watchers.py

@@ -88,7 +88,7 @@ class ModeRegistryWatcher:
 
     def changes(self) -> Iterator[Any]:
         """Yield ``WatchModeRegistryResponse`` items from the runtime stream."""
-        yield from self._client.watch_mode_registry()
+        yield from self._client.watch_mode_registry(auth=self._auth)
 
     def watch(self, handler: Callable[[Any], None]) -> None:
         """Block and invoke *handler* for each registry change."""
@@ -111,7 +111,7 @@ class RootsWatcher:
 
     def changes(self) -> Iterator[Any]:
         """Yield ``WatchRootsResponse`` items from the runtime stream."""
-        yield from self._client.watch_roots()
+        yield from self._client.watch_roots(auth=self._auth)
 
     def watch(self, handler: Callable[[Any], None]) -> None:
         """Block and invoke *handler* for each root change."""
@@ -133,8 +133,12 @@ class SignalWatcher:
         self._auth = auth
 
     def signals(self) -> Iterator[Any]:
-        """Yield envelope objects extracted from ``WatchSignalsResponse``."""
-        for response in self._client.watch_signals():
+        """Yield envelope objects extracted from ``WatchSignalsResponse``.
+
+        Forwards the watcher's stored ``auth`` — runtime v0.5.0 requires
+        authentication for ``WatchSignals``.
+        """
+        for response in self._client.watch_signals(auth=self._auth):
             if hasattr(response, "envelope") and response.envelope.ByteSize() > 0:
                 yield response.envelope
 
@@ -217,7 +221,7 @@ class PolicyWatcher:
 
     def changes(self) -> Iterator[PolicyChange]:
         """Yield ``PolicyChange`` items from the runtime stream."""
-        for response in self._client.watch_policies():
+        for response in self._client.watch_policies(auth=self._auth):
             descriptors = list(response.descriptors) if hasattr(response, "descriptors") else []
             observed = getattr(response, "observed_at_unix_ms", 0)
             yield PolicyChange(descriptors=descriptors, observed_at_unix_ms=observed)

{macp_sdk_python-0.4.1 → macp_sdk_python-0.6.0/src/macp_sdk_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: macp-sdk-python
-Version: 0.4.1
+Version: 0.6.0
 Summary: Python SDK for the MACP Rust runtime
 Author-email: Multi-Agent Coordination Protocol <macp@multiagentcoordinationprotocol.org>
 License: Apache-2.0
@@ -20,18 +20,17 @@ Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: grpcio>=1.81.1
-Requires-Dist: protobuf>=5.27.0
-Requires-Dist: macp-proto<0.2.0,>=0.1.3
+Requires-Dist: grpcio>=1.82.0rc2
+Requires-Dist: protobuf>=7.35.0
+Requires-Dist: macp-proto<0.1.9,>=0.1.6
 Provides-Extra: dev
-Requires-Dist: grpcio-tools>=1.74.0; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"
-Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
 Requires-Dist: pytest-cov>=5.0; extra == "dev"
 Requires-Dist: mypy>=1.10; extra == "dev"
 Requires-Dist: ruff>=0.5; extra == "dev"
 Requires-Dist: grpc-stubs>=1.53; extra == "dev"
 Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: jsonschema>=4.0; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.5; extra == "docs"
 Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
@@ -131,9 +130,10 @@ make setup              # pip install -e ".[dev,docs]"
 make lint               # ruff check
 make fmt                # ruff format
 make typecheck          # mypy strict
-make test               # unit tests
+make test               # unit tests + coverage gate (85% branch, from pyproject)
+make test-integration   # integration tests (auto-skip without a running runtime)
 make test-all           # lint + typecheck + all tests
-make coverage           # coverage report
+make coverage           # HTML + terminal coverage report
 
 # Build
 make build              # sdist + wheel
@@ -149,6 +149,12 @@ export MACP_ALLOW_INSECURE=1
 cargo run   # in the runtime repo
 ```
 
+Since runtime **v0.5.0**, a runtime with no authentication configured
+(`MACP_AUTH_TOKENS_*` / `MACP_AUTH_ISSUER` unset) **refuses to start** unless
+`MACP_ALLOW_INSECURE=1` is set, and the published Docker image **no longer
+bakes that env in** — pass it explicitly for local dev (as above and in the
+`docker run` command in `CLAUDE.md`).
+
 Dev-agent auth rides the standard `Authorization: Bearer` header — the
 runtime's `dev_authenticate` fallback binds the token value verbatim
 as the sender.

{macp_sdk_python-0.4.1 → macp_sdk_python-0.6.0}/src/macp_sdk_python.egg-info/requires.txt

@@ -1,16 +1,15 @@
-grpcio>=1.81.1
-protobuf>=5.27.0
-macp-proto<0.2.0,>=0.1.3
+grpcio>=1.82.0rc2
+protobuf>=7.35.0
+macp-proto<0.1.9,>=0.1.6
 
 [dev]
-grpcio-tools>=1.74.0
 pytest>=8.0
-pytest-asyncio>=0.24
 pytest-cov>=5.0
 mypy>=1.10
 ruff>=0.5
 grpc-stubs>=1.53
 build>=1.0
+jsonschema>=4.0
 
 [docs]
 mkdocs-material>=9.5