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

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/agent/runner.py

@@ -2,6 +2,8 @@ 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
@@ -9,67 +11,77 @@ 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.
+@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)
 
-    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.
+def from_bootstrap(bootstrap_path: str | None = None) -> Participant:
+    """Create a Participant from a bootstrap context file.
 
-    Expected bootstrap JSON structure::
+    Reads the flat bootstrap format produced by the examples-service::
 
         {
             "participant_id": "...",
             "session_id": "...",
             "mode": "macp.mode.decision.v1",
             "runtime_url": "localhost:50051",
-            "auth": {
-                "bearer_token": "...",   // or "agent_id": "..."
-            },
+            "auth_token": "...",
             "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
+            "secure": false,
+            "allow_insecure": true,
+            "initiator": { ... }
         }
 
-    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).
+    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, object] = json.load(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", "localhost:50051"))
+    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))
 
-    # 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
+    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,
@@ -77,16 +89,43 @@ def from_bootstrap(bootstrap_path: str | None = None) -> Participant:
         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]
+    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,
@@ -97,4 +136,5 @@ def from_bootstrap(bootstrap_path: str | None = None) -> Participant:
         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/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/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/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/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.dist-info → macp_sdk_python-0.2.2.dist-info}/METADATA

@@ -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.dist-info → macp_sdk_python-0.2.2.dist-info}/RECORD

@@ -2,11 +2,11 @@ macp_sdk/__init__.py,sha256=ASXCA-H3YkxOtpC3GAfaBUAoHU_nxboMvP_TqMUCEpY,5065
 macp_sdk/_logging.py,sha256=pHxyG89c9b_r8mcVSBA4E3e1GMAI5Jcc4_jslzKO6fM,431
 macp_sdk/auth.py,sha256=OnoLYjQTsHvj1nBMyIlcGtD-IoQy92RPXqSBKnY8ydA,2792
 macp_sdk/base_projection.py,sha256=j4mZmb2tua787qaK476xTY0o9MerjzCpT6SE1rTU8Ug,1708
-macp_sdk/base_session.py,sha256=gLXwBEmtHfYDrnPY1A1dhMP_zNvSwfIqwXea415SoFM,5903
-macp_sdk/client.py,sha256=xrkch_Ekajg9TbCVk3AAcEng-fwf6G8cOuo6OI0FEhs,23152
+macp_sdk/base_session.py,sha256=EmaWmGboFvnJnvZMKXc0A3B0XUXZZVe5kMwuBtIV_P4,5962
+macp_sdk/client.py,sha256=SJbwDyl-2qfzAUdNENUm75Dxdm2G4_f-SrZKX5i87UA,23477
 macp_sdk/constants.py,sha256=7BaQC6qycmPEc1ChOQVDxlhEBsBdI-RQBT07BQ2Uiis,481
 macp_sdk/decision.py,sha256=pjsz-KTuVw9wcDu3-ube_W6A_5pdRpV2wtupf0JgfO8,5265
-macp_sdk/envelope.py,sha256=VOK2cm9UGfL8ISkgcWLMNk1i_ZBjrrkYVjjX8xftaaY,5239
+macp_sdk/envelope.py,sha256=1sdDZPcmUcaHzgCCfZ6PcYryaf2zeNmvggy6KBDGcco,4987
 macp_sdk/errors.py,sha256=CDMe-AyMDlAm3uWZZTylkuc0LoNbPH9cK28EnvrFzjs,3260
 macp_sdk/handoff.py,sha256=EC61SdkZ_iLR6ab95G7atDhTT8Ie3SeCqHaJv8Omujo,8234
 macp_sdk/policy.py,sha256=v9F0AzgA-InNFEe2TATwmXZ_-TM0H6W5L7X14TDH1AY,8986
@@ -21,13 +21,13 @@ macp_sdk/validation.py,sha256=p2vFJ_jc25G-JseFFoUkt7oc8P1gEWtsiOepu0mh1Sk,4190
 macp_sdk/watchers.py,sha256=TlNzuC5ixF2AnCp9fh44WZhX1VLNbWCE_52gRYZ-XJU,4466
 macp_sdk/agent/__init__.py,sha256=mZWG35fCqp-80EK2cpq4N5nZ6dlQ3NDwKAboPJlp7T8,1412
 macp_sdk/agent/dispatcher.py,sha256=t1wLYGpqJdm2nIaaEVStp_8zUIetHL8FT2wYNniLDTA,3972
-macp_sdk/agent/participant.py,sha256=_pMMLtZk1DBU4amFTfjI3REeGgoaur3adm_nXMQrVzM,12732
-macp_sdk/agent/runner.py,sha256=wWVdVP4HWz5zVyu3-t2FxdS3JPYq6X1tluY-AB_eCYA,3525
+macp_sdk/agent/participant.py,sha256=yzpxK3gmetmmh3IyfomeHokVR-6szbJdmzt2ogpm00I,15509
+macp_sdk/agent/runner.py,sha256=dGvx4B2SlAsO-cqtVU8rQCPqzVxbxxsJ2Uf3ww4a5vI,5084
 macp_sdk/agent/strategies.py,sha256=oCUeTE3fhDJu96OBA_BWei7E1GbAaWvmJlgmhhRTUUo,10489
-macp_sdk/agent/transports.py,sha256=gv2U2aNYLexkNZz1cef5CIA9ubIZ9jyFi_yGEG7vT1s,5058
+macp_sdk/agent/transports.py,sha256=VU3dTNIELMTU-5kTxZOE7jxvw1NqSroUi28OkUD0NvM,5430
 macp_sdk/agent/types.py,sha256=wtlF-tTRGnEGHhYknhu-5ZzOBZ1pRQ5GjYLKBR4YzQg,1610
-macp_sdk_python-0.2.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-macp_sdk_python-0.2.1.dist-info/METADATA,sha256=OV0OZOKVxIQxM6obJTZFxafBrbPj_QCrj0kkEhHivTI,5434
-macp_sdk_python-0.2.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-macp_sdk_python-0.2.1.dist-info/top_level.txt,sha256=AoSstnUrSaVCCQw4KLxLkpO-9BLoVZ230mPBR6z-jh8,9
-macp_sdk_python-0.2.1.dist-info/RECORD,,
+macp_sdk_python-0.2.2.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+macp_sdk_python-0.2.2.dist-info/METADATA,sha256=q60i3JhbmxWK5Ne9O88Yqpvqm42A-Fv-gxt6r0aMHmI,5434
+macp_sdk_python-0.2.2.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+macp_sdk_python-0.2.2.dist-info/top_level.txt,sha256=AoSstnUrSaVCCQw4KLxLkpO-9BLoVZ230mPBR6z-jh8,9
+macp_sdk_python-0.2.2.dist-info/RECORD,,