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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: macp-sdk-python
-Version: 0.2.3
+Version: 0.4.0
 Summary: Python SDK for the MACP Rust runtime
 Author-email: OpenAI <support@openai.com>
 License: Apache-2.0
@@ -15,9 +15,9 @@ Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: grpcio>=1.74.0
+Requires-Dist: grpcio>=1.81.1
 Requires-Dist: protobuf>=5.27.0
-Requires-Dist: macp-proto<0.2.0,>=0.1.2
+Requires-Dist: macp-proto<0.2.0,>=0.1.3
 Provides-Extra: dev
 Requires-Dist: grpcio-tools>=1.74.0; extra == "dev"
 Requires-Dist: pytest>=8.0; extra == "dev"
@@ -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,9 @@ 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` / `CANCELLED` / `SUSPENDED` / `RESUMED` lifecycle events
+- Pause and cancel sessions with `MacpClient.suspend_session()` / `resume_session()` / `cancel_session()` (SDK 0.4.0 / `macp-proto 0.1.3`). A suspended session is non-terminal and rejects messages until resumed; an accepted `cancel_session()` now terminates as `CANCELLED` (previously surfaced as `EXPIRED`)
+- `ListRoots` currently returns an empty list and `WatchRoots` idles — the runtime does not yet populate roots
 - Business policy (majority, quorum, veto) belongs in your orchestrator/policy layer

{macp_sdk_python-0.2.3 → macp_sdk_python-0.4.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,9 @@ 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` / `CANCELLED` / `SUSPENDED` / `RESUMED` lifecycle events
+- Pause and cancel sessions with `MacpClient.suspend_session()` / `resume_session()` / `cancel_session()` (SDK 0.4.0 / `macp-proto 0.1.3`). A suspended session is non-terminal and rejects messages until resumed; an accepted `cancel_session()` now terminates as `CANCELLED` (previously surfaced as `EXPIRED`)
+- `ListRoots` currently returns an empty list and `WatchRoots` idles — the runtime does not yet populate roots
 - Business policy (majority, quorum, veto) belongs in your orchestrator/policy layer

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

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

{macp_sdk_python-0.2.3 → macp_sdk_python-0.4.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,
@@ -19,6 +19,7 @@ from .constants import (
 from .decision import DecisionSession
 from .envelope import (
     build_commitment_payload,
+    build_commitment_ref,
     build_envelope,
     build_progress_payload,
     build_root,
@@ -100,6 +101,8 @@ from .watchers import (
     PolicyChange,
     PolicyWatcher,
     RootsWatcher,
+    SessionLifecycle,
+    SessionLifecycleWatcher,
     SignalWatcher,
 )
 
@@ -145,6 +148,7 @@ __all__ = [
     "HandoffProjection",
     "HandoffRecord",
     "HandoffSession",
+    "InlineErrorCallback",
     "MacpAckError",
     "MacpClient",
     "MacpIdentityMismatchError",
@@ -169,6 +173,8 @@ __all__ = [
     "RejectionRules",
     "RetryPolicy",
     "RootsWatcher",
+    "SessionLifecycle",
+    "SessionLifecycleWatcher",
     "SignalWatcher",
     "TaskAssignmentRules",
     "TaskCompletionRules",
@@ -176,6 +182,7 @@ __all__ = [
     "TaskSession",
     "VotingRules",
     "build_commitment_payload",
+    "build_commitment_ref",
     "build_decision_policy",
     "build_envelope",
     "build_handoff_policy",

{macp_sdk_python-0.2.3 → macp_sdk_python-0.4.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.4.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.4.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.4.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)