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

{macp_sdk_python-0.2.3 → macp_sdk_python-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: macp-sdk-python
-Version: 0.2.3
+Version: 0.3.0
 Summary: Python SDK for the MACP Rust runtime
 Author-email: OpenAI <support@openai.com>
 License: Apache-2.0
@@ -141,10 +141,13 @@ For local development against the runtime:
 
 ```bash
 export MACP_ALLOW_INSECURE=1
-export MACP_ALLOW_DEV_SENDER_HEADER=1
 cargo run   # in the runtime repo
 ```
 
+Dev-agent auth rides the standard `Authorization: Bearer` header — the
+runtime's `dev_authenticate` fallback binds the token value verbatim
+as the sender.
+
 ## Documentation
 
 Full docs available in `docs/` — build with `mkdocs serve` after `make setup`.
@@ -160,6 +163,8 @@ Business logic — voting rules, AI decision heuristics, policy enforcement —
 
 ## Known runtime limitations
 
-- `GetSession` returns metadata only (not mode state/transcript) — hence the local projection pattern
+- `GetSession` returns metadata only (not mode state/transcript) — hence the local projection pattern; use `StreamSession` + `send_subscribe` for the full transcript
 - `StreamSession` is scoped to one session per stream; use `MacpStream.send_subscribe(session_id)` (RFC-MACP-0006-A1, since SDK 0.2.3 / `macp-proto 0.1.2`) to replay accepted history before live broadcast
+- For cross-session observability, use `MacpClient.list_sessions()` and `SessionLifecycleWatcher` (SDK 0.3.0) to enumerate active sessions and stream `CREATED` / `RESOLVED` / `EXPIRED` lifecycle events
+- `ListRoots` currently returns an empty list and `WatchRoots` idles — the runtime does not yet populate roots
 - Business policy (majority, quorum, veto) belongs in your orchestrator/policy layer

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

@@ -107,10 +107,13 @@ For local development against the runtime:
 
 ```bash
 export MACP_ALLOW_INSECURE=1
-export MACP_ALLOW_DEV_SENDER_HEADER=1
 cargo run   # in the runtime repo
 ```
 
+Dev-agent auth rides the standard `Authorization: Bearer` header — the
+runtime's `dev_authenticate` fallback binds the token value verbatim
+as the sender.
+
 ## Documentation
 
 Full docs available in `docs/` — build with `mkdocs serve` after `make setup`.
@@ -126,6 +129,8 @@ Business logic — voting rules, AI decision heuristics, policy enforcement —
 
 ## Known runtime limitations
 
-- `GetSession` returns metadata only (not mode state/transcript) — hence the local projection pattern
+- `GetSession` returns metadata only (not mode state/transcript) — hence the local projection pattern; use `StreamSession` + `send_subscribe` for the full transcript
 - `StreamSession` is scoped to one session per stream; use `MacpStream.send_subscribe(session_id)` (RFC-MACP-0006-A1, since SDK 0.2.3 / `macp-proto 0.1.2`) to replay accepted history before live broadcast
+- For cross-session observability, use `MacpClient.list_sessions()` and `SessionLifecycleWatcher` (SDK 0.3.0) to enumerate active sessions and stream `CREATED` / `RESOLVED` / `EXPIRED` lifecycle events
+- `ListRoots` currently returns an empty list and `WatchRoots` idles — the runtime does not yet populate roots
 - Business policy (majority, quorum, veto) belongs in your orchestrator/policy layer

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

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

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

@@ -2,7 +2,7 @@ from ._logging import configure_logging
 from .auth import AuthConfig
 from .base_projection import BaseProjection
 from .base_session import BaseSession
-from .client import MacpClient, MacpStream
+from .client import InlineErrorCallback, MacpClient, MacpStream
 from .constants import (
     DEFAULT_CONFIGURATION_VERSION,
     DEFAULT_MODE_VERSION,
@@ -100,6 +100,8 @@ from .watchers import (
     PolicyChange,
     PolicyWatcher,
     RootsWatcher,
+    SessionLifecycle,
+    SessionLifecycleWatcher,
     SignalWatcher,
 )
 
@@ -145,6 +147,7 @@ __all__ = [
     "HandoffProjection",
     "HandoffRecord",
     "HandoffSession",
+    "InlineErrorCallback",
     "MacpAckError",
     "MacpClient",
     "MacpIdentityMismatchError",
@@ -169,6 +172,8 @@ __all__ = [
     "RejectionRules",
     "RetryPolicy",
     "RootsWatcher",
+    "SessionLifecycle",
+    "SessionLifecycleWatcher",
     "SignalWatcher",
     "TaskAssignmentRules",
     "TaskCompletionRules",

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

@@ -1,5 +1,6 @@
+from .cancel_callback import CancelCallbackServer, start_cancel_callback_server
 from .dispatcher import Dispatcher
-from .participant import Participant, ParticipantActions
+from .participant import InitiatorConfig, Participant, ParticipantActions
 from .runner import from_bootstrap
 from .strategies import (
     CommitmentDecision,
@@ -33,6 +34,7 @@ from .types import (
 )
 
 __all__ = [
+    "CancelCallbackServer",
     "CommitmentDecision",
     "CommitmentStrategy",
     "Dispatcher",
@@ -42,6 +44,7 @@ __all__ = [
     "HandlerContext",
     "HttpTransportAdapter",
     "IncomingMessage",
+    "InitiatorConfig",
     "MessageHandler",
     "Participant",
     "ParticipantActions",
@@ -60,5 +63,6 @@ __all__ = [
     "function_voter",
     "majority_committer",
     "majority_voter",
+    "start_cancel_callback_server",
     "voting_handler",
 ]

macp_sdk_python-0.3.0/src/macp_sdk/agent/cancel_callback.py

@@ -0,0 +1,149 @@
+"""Cancel-callback HTTP endpoint (RFC-0001 §7.2 Option A).
+
+The examples-service's ``BootstrapPayload.cancel_callback`` field asks
+each agent to listen on ``http://host:port{path}`` for a ``POST`` whose
+JSON body is ``{"runId": ..., "reason": ...}``. Receipt of the POST
+should stop the participant cleanly — typically by calling
+``Participant.stop()``.
+
+Before this module every agent had to hand-roll the HTTP endpoint (see
+``examples-service/src/example-agents/runtime/risk-decider.worker.ts``
+for the TS reference). ``start_cancel_callback_server`` encapsulates
+that so callers only supply the ``on_cancel`` callback; the server
+runs in a daemon thread backed by the stdlib ``http.server`` — no new
+dependencies.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+from .._logging import logger
+
+_OnCancel = Callable[[str, str], None]
+
+
+@dataclass
+class CancelCallbackServer:
+    """Handle returned by :func:`start_cancel_callback_server`."""
+
+    address: tuple[str, int]
+    _httpd: HTTPServer
+    _thread: threading.Thread
+
+    def close(self) -> None:
+        """Stop accepting requests and tear down the HTTP server.
+
+        Safe to call from any thread — including from the very handler
+        that just fired ``on_cancel`` (which is the normal case when a
+        ``Participant.stop()`` call bubbles back here). Calling
+        ``httpd.shutdown()`` directly from the server thread would
+        self-deadlock because ``shutdown()`` blocks until
+        ``serve_forever()`` exits, so spawn a one-shot thread to
+        perform the teardown.
+        """
+        shutter = threading.Thread(
+            target=self._shutdown_once,
+            name=f"macp-cancel-callback-shutdown-{self.address[1]}",
+            daemon=True,
+        )
+        shutter.start()
+        # Only block if we're not on the server thread (avoid deadlock).
+        if threading.current_thread() is not self._thread:
+            shutter.join(timeout=2.0)
+
+    def _shutdown_once(self) -> None:
+        try:
+            self._httpd.shutdown()
+        except Exception:
+            logger.debug("cancel_callback shutdown already in progress")
+        with contextlib.suppress(Exception):
+            self._httpd.server_close()
+        if self._thread.is_alive() and threading.current_thread() is not self._thread:
+            self._thread.join(timeout=2.0)
+
+    @property
+    def port(self) -> int:
+        return self.address[1]
+
+
+def start_cancel_callback_server(
+    *,
+    host: str,
+    port: int,
+    path: str,
+    on_cancel: _OnCancel,
+) -> CancelCallbackServer:
+    """Start a minimal HTTP server that invokes ``on_cancel`` on POST.
+
+    The server binds to ``(host, port)`` — pass ``port=0`` to let the OS
+    pick a free port; the actual port is available on the returned
+    handle's ``address`` tuple. Only the exact ``path`` is honoured;
+    other paths respond with 404.
+
+    ``on_cancel`` receives ``(run_id, reason)`` parsed from the JSON
+    body. Either argument is ``""`` when missing. The callback is
+    invoked on the HTTP server thread, so it must not block the event
+    loop of the thing it's cancelling — typically it calls
+    ``participant.stop()``, which only sets a flag.
+    """
+    normalised_path = path if path.startswith("/") else "/" + path
+
+    class _Handler(BaseHTTPRequestHandler):
+        def log_message(self, fmt: str, *args: object) -> None:
+            logger.debug("cancel_callback %s - %s", self.address_string(), fmt % args)
+
+        def do_POST(self) -> None:
+            if self.path != normalised_path:
+                self.send_response(404)
+                self.end_headers()
+                return
+
+            length = int(self.headers.get("Content-Length") or 0)
+            raw = self.rfile.read(length) if length else b""
+            try:
+                body = json.loads(raw.decode("utf-8")) if raw else {}
+            except (ValueError, UnicodeDecodeError):
+                body = {}
+
+            run_id = str(body.get("runId") or body.get("run_id") or "")
+            reason = str(body.get("reason") or "")
+            logger.info("cancel_callback invoked (run=%s reason=%s)", run_id, reason)
+
+            try:
+                on_cancel(run_id, reason)
+            except Exception:
+                logger.exception("cancel_callback handler raised")
+                self.send_response(500)
+                self.end_headers()
+                return
+
+            self.send_response(202)  # Accepted — cancellation acknowledged, async
+            self.send_header("Content-Type", "application/json")
+            self.end_headers()
+            self.wfile.write(b'{"ok":true}')
+
+    httpd = HTTPServer((host, port), _Handler)
+    # ``server_address`` is typed as a variant union on stdlib stubs; normalise
+    # to the plain ``(host, port)`` pair we expose on the handle.
+    bound_host = str(httpd.server_address[0])
+    bound_port = int(httpd.server_address[1])
+    address: tuple[str, int] = (bound_host, bound_port)
+    thread = threading.Thread(
+        target=httpd.serve_forever,
+        name=f"macp-cancel-callback-{bound_host}-{bound_port}",
+        daemon=True,
+    )
+    thread.start()
+    logger.debug(
+        "cancel_callback listening on http://%s:%d%s",
+        bound_host,
+        bound_port,
+        normalised_path,
+    )
+    return CancelCallbackServer(address=address, _httpd=httpd, _thread=thread)

{macp_sdk_python-0.2.3 → macp_sdk_python-0.3.0}/src/macp_sdk/agent/participant.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from dataclasses import dataclass, field
 from typing import Any
 
 from .._logging import logger
@@ -39,6 +40,38 @@ _MODE_PROJECTIONS: dict[str, type[BaseProjection]] = {
     MODE_HANDOFF: HandoffProjection,
 }
 
+# Canonical set of terminal projection phases across all modes. Mirrors
+# ``TERMINAL_PHASES`` in typescript-sdk/src/agent/participant.ts so that both
+# SDKs fire ``on_terminal`` at the same observable point in a session. When a
+# mode introduces a new terminal phase, add it here and in the TypeScript SDK
+# in the same change.
+TERMINAL_PHASES: frozenset[str] = frozenset(
+    {"Committed", "Accepted", "Declined", "Cancelled", "TerminalRejected"}
+)
+
+
+@dataclass
+class InitiatorConfig:
+    """Configuration for an initiator agent's SessionStart + kickoff.
+
+    Parity with typescript-sdk's ``InitiatorConfig`` interface. Passed to
+    :class:`Participant` via ``initiator_config``; when set, the participant
+    emits ``SessionStart`` (and, if configured, a kickoff envelope) before
+    opening the stream.
+    """
+
+    intent: str
+    participants: list[str]
+    ttl_ms: int
+    context_id: str = ""
+    extensions: dict[str, bytes] = field(default_factory=dict)
+    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)
+
 
 class ParticipantActions:
     """Thin wrapper providing action methods bound to a participant's session."""
@@ -264,7 +297,7 @@ class Participant:
         configuration_version: str | None = None,
         policy_version: str | None = None,
         transport: TransportAdapter | None = None,
-        initiator_config: Any | None = None,
+        initiator_config: InitiatorConfig | None = None,
     ) -> None:
         self._participant_id = participant_id
         self._session_id = session_id
@@ -299,6 +332,7 @@ class Participant:
         )
         self._last_phase: str | None = None
         self._transport = transport
+        self._cancel_callback_server: Any | None = None
 
     @property
     def participant_id(self) -> str:
@@ -353,58 +387,89 @@ class Participant:
         )
 
     def _process_envelope(self, envelope: Any) -> None:
-        """Process a single envelope: update projection, dispatch handlers."""
-        # Update the projection if available
+        """Process a single envelope: apply projection, dispatch handlers,
+        and fire phase-change / terminal handlers on phase transitions.
+
+        Terminal dispatch is primarily driven by projection phase
+        transitioning into :data:`TERMINAL_PHASES` — matches TypeScript SDK
+        semantics so both SDKs fire ``on_terminal`` at the same observable
+        point. As a fallback (for envelopes projections don't model — e.g.
+        ``SessionCancel``), we fire terminal on the message type itself so
+        clients always get a ``stop`` signal for end-of-session envelopes.
+        """
         if self._projection is not None:
             self._projection.apply_envelope(envelope)
 
-        # Check for terminal messages
-        if envelope.message_type == "Commitment":
-            result = TerminalResult(
-                state="Committed",
-                commitment=envelope,
-            )
-            self._dispatcher.dispatch_terminal(result)
-            self._stopped = True
-            return
-
-        if envelope.message_type == "SessionCancel":
-            result = TerminalResult(state="Cancelled")
-            self._dispatcher.dispatch_terminal(result)
-            self._stopped = True
-            return
-
-        # Build the message and context
         message = _envelope_to_message(envelope)
         ctx = self._build_context()
 
-        # Dispatch message handler
+        # Dispatch message handler first, so handlers see the post-apply
+        # projection state.
         self._dispatcher.dispatch(message, ctx)
 
-        # Check for phase changes
+        fired_terminal = False
+
+        # Phase transition path — drives both on_phase_change and on_terminal.
         if self._projection is not None:
             current_phase = self._projection.phase
             if current_phase and current_phase != self._last_phase:
-                self._dispatcher.dispatch_phase_change(current_phase, ctx)
                 self._last_phase = current_phase
+                self._dispatcher.dispatch_phase_change(current_phase, ctx)
+
+                if current_phase in TERMINAL_PHASES:
+                    commitment = getattr(self._projection, "commitment", None)
+                    result = TerminalResult(
+                        state=current_phase,
+                        commitment=commitment
+                        if commitment is not None
+                        else envelope
+                        if envelope.message_type == "Commitment"
+                        else None,
+                    )
+                    self._dispatcher.dispatch_terminal(result)
+                    self._stopped = True
+                    fired_terminal = True
+
+        # Fallback for envelopes projections don't transition phase on —
+        # principally ``SessionCancel``. Keeps terminal dispatch reliable
+        # while the phase-driven path remains primary.
+        if not fired_terminal and envelope.message_type == "SessionCancel":
+            self._dispatcher.dispatch_terminal(TerminalResult(state="Cancelled"))
+            self._stopped = True
 
     def _process_message(self, message: IncomingMessage) -> None:
-        """Process a pre-built IncomingMessage (from HTTP transport)."""
+        """Process a pre-built :class:`IncomingMessage` (from an HTTP polling
+        transport that decodes envelopes upstream).
+
+        Terminal dispatch follows the same phase-driven model as
+        :meth:`_process_envelope`; since HTTP transports may not carry raw
+        envelopes, we fall back to a message-type check for terminal events
+        only when no projection is attached.
+        """
         ctx = self._build_context()
 
-        if message.message_type == "Commitment":
-            result = TerminalResult(state="Committed")
-            self._dispatcher.dispatch_terminal(result)
-            self._stopped = True
-            return
+        self._dispatcher.dispatch(message, ctx)
 
-        if message.message_type == "SessionCancel":
-            result = TerminalResult(state="Cancelled")
-            self._dispatcher.dispatch_terminal(result)
-            self._stopped = True
+        if self._projection is not None:
+            current_phase = self._projection.phase
+            if current_phase and current_phase != self._last_phase:
+                self._last_phase = current_phase
+                self._dispatcher.dispatch_phase_change(current_phase, ctx)
+
+                if current_phase in TERMINAL_PHASES:
+                    commitment = getattr(self._projection, "commitment", None)
+                    result = TerminalResult(state=current_phase, commitment=commitment)
+                    self._dispatcher.dispatch_terminal(result)
+                    self._stopped = True
             return
 
-        self._dispatcher.dispatch(message, ctx)
+        # No projection attached — use message-type heuristic for terminal.
+        if message.message_type == "Commitment":
+            self._dispatcher.dispatch_terminal(TerminalResult(state="Committed"))
+            self._stopped = True
+        elif message.message_type == "SessionCancel":
+            self._dispatcher.dispatch_terminal(TerminalResult(state="Cancelled"))
+            self._stopped = True
 
     def run(self) -> None:
         """Enter the blocking event loop.
@@ -453,6 +518,7 @@ class Participant:
             participants=cfg.participants,
             ttl_ms=cfg.ttl_ms,
             context_id=cfg.context_id,
+            extensions=cfg.extensions or None,
             mode_version=cfg.mode_version,
             configuration_version=cfg.configuration_version,
             policy_version=cfg.policy_version,
@@ -476,5 +542,25 @@ class Participant:
         self._process_envelope(envelope)
 
     def stop(self) -> None:
-        """Signal the event loop to stop."""
+        """Signal the event loop to stop.
+
+        Also shuts down a bound cancel-callback HTTP server (if one was
+        started by :func:`from_bootstrap` for this participant).
+        """
         self._stopped = True
+        server = self._cancel_callback_server
+        if server is not None:
+            self._cancel_callback_server = None
+            try:
+                server.close()
+            except Exception:
+                logger.exception("cancel_callback server close failed")
+
+    def attach_cancel_callback_server(self, server: Any) -> None:
+        """Attach a :class:`CancelCallbackServer` to this participant.
+
+        The server's lifetime is then tied to :meth:`stop` — the event
+        loop exit (or an incoming cancel POST that calls ``stop``) shuts
+        it down.
+        """
+        self._cancel_callback_server = server

{macp_sdk_python-0.2.3 → macp_sdk_python-0.3.0}/src/macp_sdk/agent/runner.py

@@ -1,30 +1,38 @@
 from __future__ import annotations
 
+import base64
+import binascii
 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
+from .participant import InitiatorConfig, Participant
 
+__all__ = ["InitiatorConfig", "from_bootstrap"]
 
-@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 _decode_extensions(raw: Any) -> dict[str, bytes]:
+    """Coerce a bootstrap ``session_start.extensions`` map into ``dict[str, bytes]``.
+
+    The protobuf ``map<string, bytes>`` is JSON-encoded as base64 strings
+    (proto-JSON canonical), so try base64 first and fall back to raw
+    UTF-8 bytes for hand-authored bootstraps.
+    """
+    if not isinstance(raw, dict):
+        return {}
+    decoded: dict[str, bytes] = {}
+    for key, value in raw.items():
+        if isinstance(value, bytes):
+            decoded[str(key)] = value
+        elif isinstance(value, str):
+            try:
+                decoded[str(key)] = base64.b64decode(value, validate=True)
+            except (binascii.Error, ValueError):
+                decoded[str(key)] = value.encode("utf-8")
+    return decoded
 
 
 def from_bootstrap(bootstrap_path: str | None = None) -> Participant:
@@ -116,6 +124,7 @@ def from_bootstrap(bootstrap_path: str | None = None) -> Participant:
             participants=[str(p) for p in ss.get("participants", participants)],
             ttl_ms=int(ss.get("ttl_ms", 300000)),
             context_id=str(ss.get("context_id", "")),
+            extensions=_decode_extensions(ss.get("extensions")),
             roots=ss.get("roots"),
             mode_version=_str_or("mode_version", mode_version),
             configuration_version=_str_or("configuration_version", configuration_version),
@@ -126,7 +135,7 @@ def from_bootstrap(bootstrap_path: str | None = None) -> Participant:
             kickoff_payload=kickoff.get("payload", {}) if kickoff else {},
         )
 
-    return Participant(
+    participant = Participant(
         participant_id=participant_id,
         session_id=session_id,
         mode=mode,
@@ -138,3 +147,44 @@ def from_bootstrap(bootstrap_path: str | None = None) -> Participant:
         policy_version=str(policy_version) if policy_version else DEFAULT_POLICY_VERSION,
         initiator_config=initiator_config,
     )
+
+    _bind_cancel_callback(participant, ctx.get("cancel_callback"))
+    return participant
+
+
+def _bind_cancel_callback(participant: Participant, raw: Any) -> None:
+    """Start a cancel-callback HTTP server bound to ``participant.stop``.
+
+    Reads the bootstrap ``cancel_callback`` field (``{host, port, path}``)
+    and, if present, launches a daemon HTTP server that calls
+    ``participant.stop()`` on POST. The server is attached to the
+    participant so its event-loop shutdown (or an incoming POST) tears
+    it down cleanly.
+
+    The bootstrap field is optional; callers that never set it see no
+    behavioural change. Reference: RFC-0001 §7.2 Option A, and the
+    TypeScript SDK's equivalent wiring in
+    ``examples-service/src/example-agents/runtime/risk-decider.worker.ts``.
+    """
+    if not isinstance(raw, dict):
+        return
+    host = str(raw.get("host") or "")
+    port = raw.get("port")
+    path = str(raw.get("path") or "")
+    if not host or port is None or not path:
+        return
+
+    # Local import so the stdlib ``http.server`` is paid for only when
+    # a bootstrap actually asks for a callback.
+    from .cancel_callback import start_cancel_callback_server
+
+    def _on_cancel(_run_id: str, _reason: str) -> None:
+        participant.stop()
+
+    server = start_cancel_callback_server(
+        host=host,
+        port=int(port),
+        path=path,
+        on_cancel=_on_cancel,
+    )
+    participant.attach_cancel_callback_server(server)

{macp_sdk_python-0.2.3 → macp_sdk_python-0.3.0}/src/macp_sdk/auth.py

@@ -13,26 +13,31 @@ class AuthConfig:
     reaches the wire. Per RFC-MACP-0004 §4 the runtime derives ``sender``
     from authenticated identity, so mismatches are always rejected — this
     check just surfaces the problem earlier and more clearly.
-
-    When ``expected_sender`` is ``None`` the check is skipped (preserves
-    legacy behaviour for dev/test flows that use a single shared identity).
     """
 
     bearer_token: str | None = None
-    agent_id: str | None = None
     sender_hint: str | None = None
     expected_sender: str | None = None
 
     def __post_init__(self) -> None:
-        if self.bearer_token and self.agent_id:
-            raise ValueError("choose either bearer_token or agent_id, not both")
-        if not self.bearer_token and not self.agent_id:
-            raise ValueError("either bearer_token or agent_id is required")
+        if not self.bearer_token:
+            raise ValueError("bearer_token is required")
 
     @classmethod
     def for_dev_agent(cls, agent_id: str, *, expected_sender: str | None = None) -> AuthConfig:
+        """Build an AuthConfig for local development without a real token.
+
+        Emits ``Authorization: Bearer <agent_id>``. The runtime's
+        ``dev_authenticate`` fallback binds the bearer token value
+        verbatim as the authenticated sender, so passing the raw agent
+        id keeps participant lists like ``["coordinator", "alice"]``
+        working unchanged.
+
+        For production deployments issue real tokens via the auth
+        resolver chain and use :meth:`for_bearer` directly.
+        """
         return cls(
-            agent_id=agent_id,
+            bearer_token=agent_id,
             sender_hint=agent_id,
             expected_sender=expected_sender or agent_id,
         )
@@ -63,12 +68,7 @@ class AuthConfig:
 
     @property
     def sender(self) -> str | None:
-        return self.sender_hint or self.agent_id
+        return self.sender_hint
 
     def metadata(self) -> list[tuple[str, str]]:
-        headers: list[tuple[str, str]] = []
-        if self.bearer_token:
-            headers.append(("authorization", f"Bearer {self.bearer_token}"))
-        if self.agent_id:
-            headers.append(("x-macp-agent-id", self.agent_id))
-        return headers
+        return [("authorization", f"Bearer {self.bearer_token}")]

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

@@ -24,6 +24,12 @@ from .errors import (
     MacpTransportError,
 )
 
+# Public typing alias for inline stream-error callbacks. Parity with
+# typescript-sdk's ``InlineErrorCallback``. Receives the protobuf
+# ``StreamError`` (or a legacy error object) for application-level errors
+# that do NOT tear down the stream — consumers typically log and continue.
+InlineErrorCallback = Callable[[Any], None]
+
 
 def _parse_ack_reasons(ack: object) -> list[str]:
     """Extract structured denial reasons from an ACK error's details."""
@@ -65,7 +71,7 @@ def _parse_grpc_metadata_reasons(rpc_error: grpc.RpcError) -> list[str]:
 
 def _default_capabilities() -> core_pb2.Capabilities:
     return core_pb2.Capabilities(
-        sessions=core_pb2.SessionsCapability(stream=True),
+        sessions=core_pb2.SessionsCapability(stream=True, list_sessions=True, watch_sessions=True),
         cancellation=core_pb2.CancellationCapability(cancel_session=True),
         progress=core_pb2.ProgressCapability(progress=True),
         manifest=core_pb2.ManifestCapability(get_manifest=True),
@@ -91,7 +97,7 @@ class MacpStream:
         self._requests: queue.Queue[object] = queue.Queue()
         self._responses: queue.Queue[object] = queue.Queue()
         self._closed = False
-        self._inline_error_callbacks: list[Callable[[Any], None]] = []
+        self._inline_error_callbacks: list[InlineErrorCallback] = []
         self._call = stub.StreamSession(self._request_iter(), metadata=metadata, timeout=timeout)
         self._thread = threading.Thread(target=self._pump_responses, daemon=True)
         self._thread.start()
@@ -142,7 +148,7 @@ class MacpStream:
         finally:
             self._responses.put(self._END)
 
-    def on_inline_error(self, callback: Callable[[Any], None]) -> None:
+    def on_inline_error(self, callback: InlineErrorCallback) -> None:
         """Register a callback for inline application-level stream errors."""
         self._inline_error_callbacks.append(callback)
 
@@ -207,7 +213,7 @@ class MacpClient:
         root_certificates: bytes | None = None,
         default_timeout: float | None = None,
         client_name: str = "macp-sdk-python",
-        client_version: str = "0.2.3",
+        client_version: str = "0.3.0",
     ) -> None:
         if secure is None:
             secure = not allow_insecure
@@ -415,6 +421,54 @@ class MacpClient:
             timeout=timeout or self.default_timeout,
         )
 
+    def list_sessions(
+        self,
+        *,
+        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``.
+        """
+        auth_cfg = self._require_auth(auth)
+        resp = self.stub.ListSessions(
+            core_pb2.ListSessionsRequest(),
+            metadata=self._metadata(auth_cfg),
+            timeout=timeout or self.default_timeout,
+        )
+        return list(resp.sessions)
+
+    def watch_sessions(
+        self,
+        *,
+        auth: AuthConfig | None = None,
+        timeout: float | None = None,
+    ) -> Iterator[core_pb2.WatchSessionsResponse]:
+        """Server-streaming RPC: yields session lifecycle events.
+
+        The runtime emits an initial ``EVENT_TYPE_CREATED`` frame for every
+        currently-open session, then live events as sessions transition
+        through ``CREATED``, ``RESOLVED``, and ``EXPIRED``. Each event
+        carries a full ``SessionMetadata`` (including ``context_id`` and
+        ``extension_keys``), so callers can project run state without a
+        follow-up ``get_session``.
+        """
+        logger.debug("watch_sessions starting")
+        auth_cfg = self._require_auth(auth)
+        call = self.stub.WatchSessions(
+            core_pb2.WatchSessionsRequest(),
+            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
+
     def register_ext_mode(
         self,
         descriptor: core_pb2.ModeDescriptor,

{macp_sdk_python-0.2.3 → macp_sdk_python-0.3.0}/src/macp_sdk/quorum.py

@@ -113,7 +113,11 @@ class QuorumProjection(BaseProjection):
     def abstention_count(self, request_id: str) -> int:
         return self._count_votes(request_id, "abstain")
 
-    def is_threshold_reached(self, request_id: str) -> bool:
+    def has_quorum(self, request_id: str) -> bool:
+        """True if the approval count has reached the required threshold.
+
+        Canonical name across SDKs (parity with TypeScript ``hasQuorum``).
+        """
         req = self.requests.get(request_id)
         if req is None:
             return False
@@ -128,8 +132,16 @@ class QuorumProjection(BaseProjection):
         return self.approval_count(request_id) + remaining < req.required_approvals
 
     def commitment_ready(self, request_id: str) -> bool:
-        """True if the threshold is reached."""
-        return self.is_threshold_reached(request_id)
+        """True if quorum is reached and commit has not yet been issued.
+
+        Canonical cross-SDK semantics (parity with TypeScript
+        ``QuorumProjection.commitmentReady``): ``has_quorum`` alone is
+        insufficient — once the session has moved to the ``Committed``
+        phase, the commit is no longer "ready" because it has already
+        happened. Callers that want the pure threshold-reached check
+        should use :meth:`has_quorum`.
+        """
+        return self.has_quorum(request_id) and self.phase != "Committed"
 
     def threshold(self, request_id: str) -> int:
         """Return the required approval count, or 0 if no request yet."""

{macp_sdk_python-0.2.3 → macp_sdk_python-0.3.0}/src/macp_sdk/task.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import warnings
 from dataclasses import dataclass
 
 from macp.modes.task.v1 import task_pb2
@@ -213,7 +214,7 @@ class TaskSession(BaseSession):
         assert isinstance(self.projection, TaskProjection)
         return self.projection
 
-    def request(
+    def request_task(
         self,
         task_id: str,
         title: str,
@@ -225,6 +226,9 @@ class TaskSession(BaseSession):
         sender: str | None = None,
         auth: AuthConfig | None = None,
     ) -> envelope_pb2.Ack:
+        """Send a TaskRequest envelope. Canonical name across SDKs
+        (parity with TypeScript ``requestTask``).
+        """
         payload = task_pb2.TaskRequestPayload(
             task_id=task_id,
             title=title,
@@ -242,6 +246,15 @@ class TaskSession(BaseSession):
         )
         return self._send_and_track(envelope, auth=auth)
 
+    def request(self, *args: object, **kwargs: object) -> envelope_pb2.Ack:
+        """Deprecated alias for :meth:`request_task`."""
+        warnings.warn(
+            "TaskSession.request() is deprecated; use request_task() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.request_task(*args, **kwargs)  # type: ignore[arg-type]
+
     def accept_task(
         self,
         task_id: str,
@@ -288,7 +301,7 @@ class TaskSession(BaseSession):
         )
         return self._send_and_track(envelope, auth=auth)
 
-    def update(
+    def update_task(
         self,
         task_id: str,
         *,
@@ -299,6 +312,9 @@ class TaskSession(BaseSession):
         sender: str | None = None,
         auth: AuthConfig | None = None,
     ) -> envelope_pb2.Ack:
+        """Send a TaskUpdate envelope. Canonical name across SDKs
+        (parity with TypeScript ``updateTask``).
+        """
         payload = task_pb2.TaskUpdatePayload(
             task_id=task_id,
             status=status,
@@ -315,7 +331,16 @@ class TaskSession(BaseSession):
         )
         return self._send_and_track(envelope, auth=auth)
 
-    def complete(
+    def update(self, *args: object, **kwargs: object) -> envelope_pb2.Ack:
+        """Deprecated alias for :meth:`update_task`."""
+        warnings.warn(
+            "TaskSession.update() is deprecated; use update_task() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.update_task(*args, **kwargs)  # type: ignore[arg-type]
+
+    def complete_task(
         self,
         task_id: str,
         *,
@@ -325,6 +350,9 @@ class TaskSession(BaseSession):
         sender: str | None = None,
         auth: AuthConfig | None = None,
     ) -> envelope_pb2.Ack:
+        """Send a TaskComplete envelope. Canonical name across SDKs
+        (parity with TypeScript ``completeTask``).
+        """
         payload = task_pb2.TaskCompletePayload(
             task_id=task_id,
             assignee=assignee or self._sender_for(sender, auth=auth),
@@ -340,7 +368,16 @@ class TaskSession(BaseSession):
         )
         return self._send_and_track(envelope, auth=auth)
 
-    def fail(
+    def complete(self, *args: object, **kwargs: object) -> envelope_pb2.Ack:
+        """Deprecated alias for :meth:`complete_task`."""
+        warnings.warn(
+            "TaskSession.complete() is deprecated; use complete_task() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.complete_task(*args, **kwargs)  # type: ignore[arg-type]
+
+    def fail_task(
         self,
         task_id: str,
         *,
@@ -351,6 +388,9 @@ class TaskSession(BaseSession):
         sender: str | None = None,
         auth: AuthConfig | None = None,
     ) -> envelope_pb2.Ack:
+        """Send a TaskFail envelope. Canonical name across SDKs
+        (parity with TypeScript ``failTask``).
+        """
         payload = task_pb2.TaskFailPayload(
             task_id=task_id,
             assignee=assignee or self._sender_for(sender, auth=auth),
@@ -366,3 +406,12 @@ class TaskSession(BaseSession):
             payload=serialize_message(payload),
         )
         return self._send_and_track(envelope, auth=auth)
+
+    def fail(self, *args: object, **kwargs: object) -> envelope_pb2.Ack:
+        """Deprecated alias for :meth:`fail_task`."""
+        warnings.warn(
+            "TaskSession.fail() is deprecated; use fail_task() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.fail_task(*args, **kwargs)  # type: ignore[arg-type]

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

@@ -25,6 +25,38 @@ class PolicyChange:
     observed_at_unix_ms: int = 0
 
 
+@dataclass(slots=True)
+class SessionLifecycle:
+    """A single session lifecycle event from ``WatchSessions``.
+
+    Runtime event types (per ``SessionLifecycleEvent.EventType``): ``CREATED``
+    on SessionStart acceptance (also emitted for pre-existing sessions at
+    subscribe time), ``RESOLVED`` on mode-determined terminal outcome,
+    ``EXPIRED`` on TTL expiry or explicit ``CancelSession``.
+    """
+
+    event_type: str = "UNSPECIFIED"
+    observed_at_unix_ms: int = 0
+    session: Any = None
+
+    @property
+    def is_created(self) -> bool:
+        return self.event_type == "CREATED"
+
+    @property
+    def is_resolved(self) -> bool:
+        return self.event_type == "RESOLVED"
+
+    @property
+    def is_expired(self) -> bool:
+        return self.event_type == "EXPIRED"
+
+    @property
+    def is_terminal(self) -> bool:
+        """``True`` for RESOLVED or EXPIRED — the session won't emit more events."""
+        return self.event_type in ("RESOLVED", "EXPIRED")
+
+
 class ModeRegistryWatcher:
     """Watch for mode registry changes from the runtime."""
 
@@ -96,6 +128,63 @@ class SignalWatcher:
         raise RuntimeError("stream ended before receiving a signal")
 
 
+_SESSION_EVENT_PREFIX = "EVENT_TYPE_"
+
+
+def _session_event_name(event_type: int) -> str:
+    """Map ``SessionLifecycleEvent.EventType`` enum ints to short string names.
+
+    The proto enum spells values as ``EVENT_TYPE_CREATED``; strip the
+    prefix so consumers can compare against ``"CREATED"`` without
+    importing the proto module.
+    """
+    from macp.v1 import core_pb2
+
+    name = core_pb2.SessionLifecycleEvent.EventType.Name(event_type)
+    if name.startswith(_SESSION_EVENT_PREFIX):
+        return name[len(_SESSION_EVENT_PREFIX) :]
+    return name
+
+
+class SessionLifecycleWatcher:
+    """Watch for session lifecycle events from the runtime.
+
+    Wraps ``MacpClient.watch_sessions()`` and normalises each response into
+    a ``SessionLifecycle`` record carrying the event type as a short
+    string (``CREATED`` / ``RESOLVED`` / ``EXPIRED``) and the full
+    ``SessionMetadata``. The runtime emits an initial CREATED event for
+    every already-open session at subscribe time, then live events
+    thereafter — see ``runtime/src/server.rs::watch_sessions``.
+    """
+
+    def __init__(self, client: MacpClient, *, auth: AuthConfig | None = None) -> None:
+        self._client = client
+        self._auth = auth
+
+    def changes(self) -> Iterator[SessionLifecycle]:
+        """Yield ``SessionLifecycle`` items from the runtime stream."""
+        for response in self._client.watch_sessions(auth=self._auth):
+            event = getattr(response, "event", None)
+            if event is None:
+                continue
+            yield SessionLifecycle(
+                event_type=_session_event_name(event.event_type),
+                observed_at_unix_ms=event.observed_at_unix_ms,
+                session=event.session,
+            )
+
+    def watch(self, handler: Callable[[SessionLifecycle], None]) -> None:
+        """Block and invoke *handler* for each lifecycle event."""
+        for change in self.changes():
+            handler(change)
+
+    def next_change(self) -> SessionLifecycle:
+        """Pull a single lifecycle event from the stream and return it."""
+        for change in self.changes():
+            return change
+        raise RuntimeError("stream ended before receiving a session lifecycle event")
+
+
 class PolicyWatcher:
     """Watch for governance policy changes from the runtime."""
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: macp-sdk-python
-Version: 0.2.3
+Version: 0.3.0
 Summary: Python SDK for the MACP Rust runtime
 Author-email: OpenAI <support@openai.com>
 License: Apache-2.0
@@ -141,10 +141,13 @@ For local development against the runtime:
 
 ```bash
 export MACP_ALLOW_INSECURE=1
-export MACP_ALLOW_DEV_SENDER_HEADER=1
 cargo run   # in the runtime repo
 ```
 
+Dev-agent auth rides the standard `Authorization: Bearer` header — the
+runtime's `dev_authenticate` fallback binds the token value verbatim
+as the sender.
+
 ## Documentation
 
 Full docs available in `docs/` — build with `mkdocs serve` after `make setup`.
@@ -160,6 +163,8 @@ Business logic — voting rules, AI decision heuristics, policy enforcement —
 
 ## Known runtime limitations
 
-- `GetSession` returns metadata only (not mode state/transcript) — hence the local projection pattern
+- `GetSession` returns metadata only (not mode state/transcript) — hence the local projection pattern; use `StreamSession` + `send_subscribe` for the full transcript
 - `StreamSession` is scoped to one session per stream; use `MacpStream.send_subscribe(session_id)` (RFC-MACP-0006-A1, since SDK 0.2.3 / `macp-proto 0.1.2`) to replay accepted history before live broadcast
+- For cross-session observability, use `MacpClient.list_sessions()` and `SessionLifecycleWatcher` (SDK 0.3.0) to enumerate active sessions and stream `CREATED` / `RESOLVED` / `EXPIRED` lifecycle events
+- `ListRoots` currently returns an empty list and `WatchRoots` idles — the runtime does not yet populate roots
 - Business policy (majority, quorum, veto) belongs in your orchestrator/policy layer

{macp_sdk_python-0.2.3 → macp_sdk_python-0.3.0}/src/macp_sdk_python.egg-info/SOURCES.txt

@@ -23,6 +23,7 @@ src/macp_sdk/task.py
 src/macp_sdk/validation.py
 src/macp_sdk/watchers.py
 src/macp_sdk/agent/__init__.py
+src/macp_sdk/agent/cancel_callback.py
 src/macp_sdk/agent/dispatcher.py
 src/macp_sdk/agent/participant.py
 src/macp_sdk/agent/runner.py