macp-sdk-python 0.2.1__tar.gz → 0.2.2__tar.gz

{macp_sdk_python-0.2.1/src/macp_sdk_python.egg-info → macp_sdk_python-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: macp-sdk-python
-Version: 0.2.1
+Version: 0.2.2
 Summary: Python SDK for the MACP Rust runtime
 Author-email: OpenAI <support@openai.com>
 License: Apache-2.0
@@ -17,7 +17,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: grpcio>=1.74.0
 Requires-Dist: protobuf>=5.27.0
-Requires-Dist: macp-proto<0.2.0,>=0.1.0
+Requires-Dist: macp-proto<0.2.0,>=0.1.1
 Provides-Extra: dev
 Requires-Dist: grpcio-tools>=1.74.0; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"

{macp_sdk_python-0.2.1 → macp_sdk_python-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "macp-sdk-python"
-version = "0.2.1"
+version = "0.2.2"
 description = "Python SDK for the MACP Rust runtime"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -25,10 +25,9 @@ classifiers = [
 dependencies = [
   "grpcio>=1.74.0",
   "protobuf>=5.27.0",
-  # Tested against 0.1.x; narrow the upper bound so a hypothetical 0.2.0
-  # proto release doesn't silently land without the conformance suite
-  # being re-run. See docs/contributing.md "Bumping macp-proto".
-  "macp-proto>=0.1.0,<0.2.0",
+  # Requires 0.1.1+ for context_id / extensions fields on SessionStartPayload.
+  # See docs/contributing.md "Bumping macp-proto".
+  "macp-proto>=0.1.1,<0.2.0",
 ]
 
 [project.optional-dependencies]

{macp_sdk_python-0.2.1 → macp_sdk_python-0.2.2}/src/macp_sdk/agent/participant.py

@@ -70,6 +70,48 @@ class ParticipantActions:
         """Cancel the session."""
         return self._client.cancel_session(self._session_id, reason=reason, auth=self._auth)
 
+    def start_session(
+        self,
+        intent: str,
+        participants: list[str],
+        ttl_ms: int,
+        context_id: str = "",
+        extensions: dict[str, bytes] | None = None,
+        mode_version: str | None = None,
+        configuration_version: str | None = None,
+        policy_version: str | None = None,
+    ) -> Any:
+        """Send a SessionStart envelope to open the session."""
+        from ..constants import (
+            DEFAULT_CONFIGURATION_VERSION,
+            DEFAULT_MODE_VERSION,
+            DEFAULT_POLICY_VERSION,
+        )
+        from ..envelope import (
+            build_envelope,
+            build_session_start_payload,
+            serialize_message,
+        )
+
+        payload = build_session_start_payload(
+            intent=intent,
+            participants=participants,
+            ttl_ms=ttl_ms,
+            context_id=context_id,
+            extensions=extensions,
+            mode_version=mode_version or DEFAULT_MODE_VERSION,
+            configuration_version=configuration_version or DEFAULT_CONFIGURATION_VERSION,
+            policy_version=policy_version or DEFAULT_POLICY_VERSION,
+        )
+        envelope = build_envelope(
+            mode=self._mode,
+            message_type="SessionStart",
+            session_id=self._session_id,
+            sender=self._participant_id,
+            payload=serialize_message(payload),
+        )
+        return self.send_envelope(envelope)
+
     def evaluate(
         self,
         proposal_id: str,
@@ -222,6 +264,7 @@ class Participant:
         configuration_version: str | None = None,
         policy_version: str | None = None,
         transport: TransportAdapter | None = None,
+        initiator_config: Any | None = None,
     ) -> None:
         self._participant_id = participant_id
         self._session_id = session_id
@@ -229,6 +272,7 @@ class Participant:
         self._client = client
         self._auth = auth
         self._stopped = False
+        self._initiator_config = initiator_config
 
         self._dispatcher = Dispatcher()
         self._session = SessionInfo(
@@ -365,19 +409,23 @@ class Participant:
     def run(self) -> None:
         """Enter the blocking event loop.
 
-        If a :class:`TransportAdapter` was provided, it is used to receive
-        messages.  Otherwise a gRPC ``StreamSession`` is opened.
+        If this participant is the initiator (``initiator_config`` is set),
+        emits SessionStart + kickoff before opening the stream.
 
         Dispatches received events to registered handlers until the session
         reaches a terminal state or ``stop()`` is called.
         """
         logger.info(
-            "participant %s joining session %s (mode=%s)",
+            "participant %s joining session %s (mode=%s, initiator=%s)",
             self._participant_id,
             self._session_id,
             self._mode,
+            self._initiator_config is not None,
         )
 
+        if self._initiator_config is not None:
+            self._emit_initiator_envelopes()
+
         transport = self._transport or GrpcTransportAdapter(
             self._client,
             self._session_id,
@@ -387,7 +435,6 @@ class Participant:
             for message in transport.start():
                 if self._stopped:
                     break
-                # If the transport yields raw envelopes (gRPC), process as envelope
                 if message.raw is not None:
                     self._process_envelope(message.raw)
                 else:
@@ -395,6 +442,35 @@ class Participant:
         finally:
             transport.stop()
 
+    def _emit_initiator_envelopes(self) -> None:
+        """Emit SessionStart + kickoff envelope as the initiator."""
+        cfg = self._initiator_config
+        if cfg is None:
+            return
+
+        self._actions.start_session(
+            intent=cfg.intent,
+            participants=cfg.participants,
+            ttl_ms=cfg.ttl_ms,
+            context_id=cfg.context_id,
+            mode_version=cfg.mode_version,
+            configuration_version=cfg.configuration_version,
+            policy_version=cfg.policy_version,
+        )
+        logger.info("SessionStart emitted (session=%s)", self._session_id)
+
+        if cfg.kickoff_message_type == "Proposal":
+            payload = cfg.kickoff_payload or {}
+            proposal_id = str(
+                payload.get("proposalId")
+                or payload.get("proposal_id")
+                or f"{self._session_id}-kickoff"
+            )
+            option = str(payload.get("option", "decide"))
+            rationale = str(payload.get("rationale", ""))
+            self._actions.propose(proposal_id, option, rationale=rationale)
+            logger.info("Kickoff proposal emitted (proposalId=%s)", proposal_id)
+
     def process_event(self, envelope: Any) -> None:
         """Manually process a single envelope (for testing or polling transports)."""
         self._process_envelope(envelope)

macp_sdk_python-0.2.2/src/macp_sdk/agent/runner.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..auth import AuthConfig
+from ..client import MacpClient
+from ..constants import DEFAULT_POLICY_VERSION
+from .participant import Participant
+
+
+@dataclass
+class InitiatorConfig:
+    """Configuration for the initiator agent's SessionStart + kickoff."""
+
+    intent: str
+    participants: list[str]
+    ttl_ms: int
+    context_id: str = ""
+    roots: list[dict[str, str]] | None = None
+    mode_version: str | None = None
+    configuration_version: str | None = None
+    policy_version: str | None = None
+    kickoff_message_type: str | None = None
+    kickoff_payload: dict[str, Any] = field(default_factory=dict)
+
+
+def from_bootstrap(bootstrap_path: str | None = None) -> Participant:
+    """Create a Participant from a bootstrap context file.
+
+    Reads the flat bootstrap format produced by the examples-service::
+
+        {
+            "participant_id": "...",
+            "session_id": "...",
+            "mode": "macp.mode.decision.v1",
+            "runtime_url": "localhost:50051",
+            "auth_token": "...",
+            "participants": ["agent-a", "agent-b"],
+            "secure": false,
+            "allow_insecure": true,
+            "initiator": { ... }
+        }
+
+    Also accepts ``auth.bearer_token`` for backwards compatibility.
+    """
+    path = bootstrap_path or os.environ.get("MACP_BOOTSTRAP_FILE")
+    if not path:
+        raise ValueError("No bootstrap path provided and MACP_BOOTSTRAP_FILE not set")
+
+    with open(path) as f:
+        ctx: dict[str, Any] = json.load(f)
+
+    participant_id = str(ctx["participant_id"])
+    session_id = str(ctx["session_id"])
+    mode = str(ctx["mode"])
+    runtime_url = str(ctx.get("runtime_url") or ctx.get("runtime_address") or "localhost:50051")
+    secure = bool(ctx.get("secure", True))
+    allow_insecure = bool(ctx.get("allow_insecure", False))
+
+    auth: AuthConfig | None = None
+    auth_token = ctx.get("auth_token")
+    agent_id = ctx.get("agent_id")
+    auth_data = ctx.get("auth")
+
+    if auth_token:
+        auth = AuthConfig.for_bearer(
+            str(auth_token),
+            sender_hint=participant_id,
+            expected_sender=participant_id,
+        )
+    elif isinstance(auth_data, dict) and auth_data.get("bearer_token"):
+        auth = AuthConfig.for_bearer(
+            str(auth_data["bearer_token"]),
+            sender_hint=participant_id,
+            expected_sender=str(auth_data.get("expected_sender") or participant_id),
+        )
+    elif agent_id:
+        auth = AuthConfig.for_dev_agent(str(agent_id), expected_sender=participant_id)
+    elif isinstance(auth_data, dict) and auth_data.get("agent_id"):
+        auth = AuthConfig.for_dev_agent(str(auth_data["agent_id"]), expected_sender=participant_id)
+
+    client = MacpClient(
+        target=runtime_url,
+        secure=secure,
+        allow_insecure=allow_insecure,
+        auth=auth,
+    )
+
+    raw_participants = ctx.get("participants")
+    participants: list[str] = (
+        [str(p) for p in raw_participants] if isinstance(raw_participants, list) else []
+    )
+
+    mode_version = ctx.get("mode_version")
+    configuration_version = ctx.get("configuration_version")
+    policy_version = ctx.get("policy_version")
+
+    initiator_config: InitiatorConfig | None = None
+    initiator_data = ctx.get("initiator")
+    if isinstance(initiator_data, dict):
+        ss = initiator_data.get("session_start", {})
+        kickoff = initiator_data.get("kickoff")
+
+        def _str_or(key: str, fallback: object) -> str | None:
+            """Pick value from session_start, then fallback, coercing to str."""
+            val = ss.get(key)
+            if val is not None:
+                return str(val)
+            return str(fallback) if fallback else None
+
+        initiator_config = InitiatorConfig(
+            intent=str(ss.get("intent", "")),
+            participants=[str(p) for p in ss.get("participants", participants)],
+            ttl_ms=int(ss.get("ttl_ms", 300000)),
+            context_id=str(ss.get("context_id", "")),
+            roots=ss.get("roots"),
+            mode_version=_str_or("mode_version", mode_version),
+            configuration_version=_str_or("configuration_version", configuration_version),
+            policy_version=_str_or("policy_version", policy_version),
+            kickoff_message_type=(
+                str(kickoff["message_type"]) if kickoff and "message_type" in kickoff else None
+            ),
+            kickoff_payload=kickoff.get("payload", {}) if kickoff else {},
+        )
+
+    return Participant(
+        participant_id=participant_id,
+        session_id=session_id,
+        mode=mode,
+        client=client,
+        auth=auth,
+        participants=participants,
+        mode_version=str(mode_version) if mode_version else None,
+        configuration_version=str(configuration_version) if configuration_version else None,
+        policy_version=str(policy_version) if policy_version else DEFAULT_POLICY_VERSION,
+        initiator_config=initiator_config,
+    )

{macp_sdk_python-0.2.1 → macp_sdk_python-0.2.2}/src/macp_sdk/agent/transports.py

@@ -133,16 +133,27 @@ class HttpTransportAdapter:
 
 def _envelope_to_message(envelope: Any) -> IncomingMessage:
     """Convert a protobuf Envelope to an IncomingMessage."""
+    from ..proto_registry import ProtoRegistry
+
     payload_dict: dict[str, Any] = {}
     if envelope.payload:
         try:
-            payload_dict = json.loads(envelope.payload)
-        except (json.JSONDecodeError, UnicodeDecodeError):
-            payload_dict = {"_raw_bytes": envelope.payload}
+            registry = ProtoRegistry()
+            decoded = registry.decode_known_payload(
+                envelope.mode, envelope.message_type, envelope.payload
+            )
+            payload_dict = decoded if decoded is not None else json.loads(envelope.payload)
+        except Exception:
+            try:
+                payload_dict = json.loads(envelope.payload)
+            except Exception:
+                payload_dict = {}
 
-    proposal_id: str | None = None
-    if "proposal_id" in payload_dict:
-        proposal_id = str(payload_dict["proposal_id"])
+    proposal_id: str | None = (
+        payload_dict.get("proposal_id") or payload_dict.get("proposalId") or None
+    )
+    if proposal_id is not None:
+        proposal_id = str(proposal_id)
 
     return IncomingMessage(
         message_type=envelope.message_type,

{macp_sdk_python-0.2.1 → macp_sdk_python-0.2.2}/src/macp_sdk/base_session.py

@@ -99,7 +99,8 @@ class BaseSession(ABC):
         intent: str,
         participants: list[str],
         ttl_ms: int,
-        context: bytes | str | Mapping[str, object] | None = None,
+        context_id: str = "",
+        extensions: Mapping[str, bytes] | None = None,
         roots: Iterable[Any] | None = None,
         sender: str | None = None,
         auth: AuthConfig | None = None,
@@ -113,7 +114,8 @@ class BaseSession(ABC):
             mode_version=self.mode_version,
             configuration_version=self.configuration_version,
             policy_version=self.policy_version,
-            context=context,
+            context_id=context_id,
+            extensions=extensions,
             roots=roots,
         )
         envelope = build_envelope(

{macp_sdk_python-0.2.1 → macp_sdk_python-0.2.2}/src/macp_sdk/client.py

@@ -107,24 +107,32 @@ class MacpStream:
     def _pump_responses(self) -> None:
         try:
             for response in self._call:
-                # Support both formats:
-                #   New: StreamSessionResponse { response: { envelope | error } }
-                #   Old: StreamSessionResponse { envelope }
+                # StreamSessionResponse has envelope + error at the top level.
+                envelope = getattr(response, "envelope", None)
+                error = getattr(response, "error", None)
+
+                if error is not None and hasattr(error, "ByteSize") and error.ByteSize() > 0:
+                    for cb in self._inline_error_callbacks:
+                        cb(error)
+                    logger.warning("inline stream error: %s", error)
+                    continue
+
+                if envelope is not None and envelope.ByteSize() > 0:
+                    self._responses.put(envelope)
+                    continue
+
+                # Fallback: try a nested .response wrapper (legacy proto shape).
                 inner = getattr(response, "response", None)
                 if inner is not None and hasattr(inner, "ByteSize") and inner.ByteSize() > 0:
-                    envelope = getattr(inner, "envelope", None)
-                    error = getattr(inner, "error", None)
-                    if envelope is not None and envelope.ByteSize() > 0:
-                        self._responses.put(envelope)
-                    elif error is not None:
-                        # Inline application-level error — notify callbacks, keep stream open
+                    inner_env = getattr(inner, "envelope", None)
+                    inner_err = getattr(inner, "error", None)
+                    if inner_env is not None and inner_env.ByteSize() > 0:
+                        self._responses.put(inner_env)
+                    elif inner_err is not None:
                         for cb in self._inline_error_callbacks:
-                            cb(error)
-                        logger.warning("inline stream error: %s", error)
+                            cb(inner_err)
+                        logger.warning("inline stream error: %s", inner_err)
                         continue
-                else:
-                    # Flat format: response.envelope
-                    self._responses.put(response.envelope)
         except grpc.RpcError as exc:
             self._responses.put(exc)
         finally:
@@ -182,7 +190,7 @@ class MacpClient:
         root_certificates: bytes | None = None,
         default_timeout: float | None = None,
         client_name: str = "macp-sdk-python",
-        client_version: str = "0.2.1",
+        client_version: str = "0.2.2",
     ) -> None:
         if secure is None:
             secure = not allow_insecure

{macp_sdk_python-0.2.1 → macp_sdk_python-0.2.2}/src/macp_sdk/envelope.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import json
 import time
 import uuid
 from collections.abc import Iterable, Mapping, Sequence
@@ -47,16 +46,6 @@ def now_unix_ms() -> int:
     return int(time.time() * 1000)
 
 
-def encode_context(context: bytes | str | Mapping[str, object] | None) -> bytes:
-    if context is None:
-        return b""
-    if isinstance(context, bytes):
-        return context
-    if isinstance(context, str):
-        return context.encode("utf-8")
-    return json.dumps(context).encode("utf-8")
-
-
 def build_root(uri: str, name: str = "") -> core_pb2.Root:
     return core_pb2.Root(uri=uri, name=name)
 
@@ -69,7 +58,8 @@ def build_session_start_payload(
     mode_version: str = DEFAULT_MODE_VERSION,
     configuration_version: str = DEFAULT_CONFIGURATION_VERSION,
     policy_version: str = DEFAULT_POLICY_VERSION,
-    context: bytes | str | Mapping[str, object] | None = None,
+    context_id: str = "",
+    extensions: Mapping[str, bytes] | None = None,
     roots: Iterable[core_pb2.Root] | None = None,
 ) -> core_pb2.SessionStartPayload:
     return core_pb2.SessionStartPayload(
@@ -79,7 +69,8 @@ def build_session_start_payload(
         configuration_version=configuration_version,
         policy_version=policy_version,
         ttl_ms=ttl_ms,
-        context=encode_context(context),
+        context_id=context_id,
+        extensions=dict(extensions) if extensions else {},
         roots=list(roots or []),
     )
 

{macp_sdk_python-0.2.1 → macp_sdk_python-0.2.2/src/macp_sdk_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: macp-sdk-python
-Version: 0.2.1
+Version: 0.2.2
 Summary: Python SDK for the MACP Rust runtime
 Author-email: OpenAI <support@openai.com>
 License: Apache-2.0
@@ -17,7 +17,7 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: grpcio>=1.74.0
 Requires-Dist: protobuf>=5.27.0
-Requires-Dist: macp-proto<0.2.0,>=0.1.0
+Requires-Dist: macp-proto<0.2.0,>=0.1.1
 Provides-Extra: dev
 Requires-Dist: grpcio-tools>=1.74.0; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"

{macp_sdk_python-0.2.1 → macp_sdk_python-0.2.2}/src/macp_sdk_python.egg-info/requires.txt

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

macp_sdk_python-0.2.1/src/macp_sdk/agent/runner.py

@@ -1,100 +0,0 @@
-from __future__ import annotations
-
-import json
-import os
-
-from ..auth import AuthConfig
-from ..client import MacpClient
-from ..constants import DEFAULT_POLICY_VERSION
-from .participant import Participant
-
-
-def from_bootstrap(bootstrap_path: str | None = None) -> Participant:
-    """Create a Participant from a bootstrap context file.
-
-    The bootstrap file is a JSON document produced by the MACP hosting
-    infrastructure containing the information needed to connect and
-    participate in a session.
-
-    If ``bootstrap_path`` is not provided, the ``MACP_BOOTSTRAP_FILE``
-    environment variable is used.
-
-    Expected bootstrap JSON structure::
-
-        {
-            "participant_id": "...",
-            "session_id": "...",
-            "mode": "macp.mode.decision.v1",
-            "runtime_url": "localhost:50051",
-            "auth": {
-                "bearer_token": "...",   // or "agent_id": "..."
-            },
-            "participants": ["agent-a", "agent-b"],
-            "policy_version": "policy.default",
-            "secure": true,              // default; set false only for local dev
-            "allow_insecure": false      // required if secure=false
-        }
-
-    Transport security follows RFC-MACP-0006 §3: ``secure`` defaults to
-    ``true``. Setting ``secure: false`` additionally requires
-    ``allow_insecure: true`` in the bootstrap (opt-in for local dev only).
-    """
-    path = bootstrap_path or os.environ.get("MACP_BOOTSTRAP_FILE")
-    if not path:
-        raise ValueError("No bootstrap path provided and MACP_BOOTSTRAP_FILE not set")
-
-    with open(path) as f:
-        ctx: dict[str, object] = json.load(f)
-
-    participant_id = str(ctx["participant_id"])
-    session_id = str(ctx["session_id"])
-    mode = str(ctx["mode"])
-    runtime_url = str(ctx.get("runtime_url", "localhost:50051"))
-    secure = bool(ctx.get("secure", True))
-    allow_insecure = bool(ctx.get("allow_insecure", False))
-
-    # Build auth config
-    auth_data = ctx.get("auth")
-    auth: AuthConfig | None = None
-    if isinstance(auth_data, dict):
-        bearer = auth_data.get("bearer_token")
-        agent_id = auth_data.get("agent_id")
-        expected_sender = auth_data.get("expected_sender") or participant_id
-        if bearer:
-            auth = AuthConfig.for_bearer(
-                str(bearer),
-                sender_hint=participant_id,
-                expected_sender=str(expected_sender),
-            )
-        elif agent_id:
-            auth = AuthConfig.for_dev_agent(str(agent_id), expected_sender=str(expected_sender))
-
-    # Build client
-    client = MacpClient(
-        target=runtime_url,
-        secure=secure,
-        allow_insecure=allow_insecure,
-        auth=auth,
-    )
-
-    # Extract optional fields
-    raw_participants = ctx.get("participants")
-    participants: list[str] = []
-    if isinstance(raw_participants, list):
-        participants = [str(p) for p in raw_participants]
-
-    mode_version = ctx.get("mode_version")
-    configuration_version = ctx.get("configuration_version")
-    policy_version = ctx.get("policy_version")
-
-    return Participant(
-        participant_id=participant_id,
-        session_id=session_id,
-        mode=mode,
-        client=client,
-        auth=auth,
-        participants=participants,
-        mode_version=str(mode_version) if mode_version else None,
-        configuration_version=str(configuration_version) if configuration_version else None,
-        policy_version=str(policy_version) if policy_version else DEFAULT_POLICY_VERSION,
-    )