cc-blackbox 0.2.0__py3-none-any.whl

cc_blackbox/__init__.py

@@ -0,0 +1,101 @@
+"""Typed access to a running Claude Code (cc): profiles, active sessions and cross-session messaging.
+
+Unofficial and not affiliated with or endorsed by Anthropic. The package relies on undocumented Claude Code internals
+that can change in any Claude Code release.
+
+Everything importable from this package is the public API. Submodules are implementation details.
+"""
+
+from cc_blackbox.compatibility import (
+    SUPPORTED_PEER_PROTOCOLS,
+    TESTED_CLAUDE_CODE_VERSIONS,
+    Compatibility,
+    CompatibilityFeature,
+    check_compatibility,
+)
+from cc_blackbox.errors import (
+    AmbiguousSession,
+    AuthSwitchConfigError,
+    ClaudeBlackboxError,
+    MessageTooLarge,
+    MessagingError,
+    MessagingUnavailable,
+    ProfileNotFound,
+    SessionGone,
+    SessionNotFound,
+    UnsupportedProtocol,
+)
+from cc_blackbox.messaging import (
+    MessagingTarget,
+    Priority,
+    RateLimitedSender,
+    SentMessage,
+    build_envelope,
+    percent_encode_address,
+    rename_session,
+    send_message,
+)
+from cc_blackbox.paths import claude_tmp_root, project_slug, scratchpad_dir
+from cc_blackbox.profiles import (
+    AuthSwitchConfig,
+    AuthSwitchProfile,
+    ClaudeProfile,
+    ProfileSource,
+    current_profile,
+    get_profile,
+    list_profiles,
+    read_auth_switch_config,
+)
+from cc_blackbox.sessions import (
+    ActiveSession,
+    SessionKind,
+    SessionStatus,
+    current_session,
+    find_session,
+    list_active_sessions,
+)
+
+__all__ = [
+    "ActiveSession",
+    "AmbiguousSession",
+    "AuthSwitchConfig",
+    "AuthSwitchConfigError",
+    "AuthSwitchProfile",
+    "ClaudeBlackboxError",
+    "ClaudeProfile",
+    "Compatibility",
+    "CompatibilityFeature",
+    "MessageTooLarge",
+    "MessagingError",
+    "MessagingTarget",
+    "MessagingUnavailable",
+    "Priority",
+    "ProfileNotFound",
+    "ProfileSource",
+    "RateLimitedSender",
+    "SUPPORTED_PEER_PROTOCOLS",
+    "SentMessage",
+    "SessionGone",
+    "SessionKind",
+    "SessionNotFound",
+    "SessionStatus",
+    "TESTED_CLAUDE_CODE_VERSIONS",
+    "UnsupportedProtocol",
+    "build_envelope",
+    "check_compatibility",
+    "claude_tmp_root",
+    "current_profile",
+    "current_session",
+    "find_session",
+    "get_profile",
+    "list_active_sessions",
+    "list_profiles",
+    "percent_encode_address",
+    "project_slug",
+    "read_auth_switch_config",
+    "rename_session",
+    "scratchpad_dir",
+    "send_message",
+]
+
+__version__ = "0.2.0"

cc_blackbox/compatibility.py

@@ -0,0 +1,112 @@
+"""Whether a running session uses the record fields and protocol this package understands.
+
+The check looks at what a session actually declares, never at its Claude Code version number. Claude Code updates
+often and usually keeps these interfaces stable, so a newer Claude Code that still writes the same fields and speaks
+the same peer protocol just works. Unknown extra record fields and unknown peer features are additions, and do not
+make a session incompatible.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from cc_blackbox.sessions.active import ActiveSession
+
+__all__ = [
+    "SUPPORTED_PEER_PROTOCOLS",
+    "TESTED_CLAUDE_CODE_VERSIONS",
+    "Compatibility",
+    "CompatibilityFeature",
+    "check_compatibility",
+]
+
+SUPPORTED_PEER_PROTOCOLS: frozenset[int] = frozenset({1})
+"""The ``peerProtocol`` values whose message frames this package can write."""
+
+TESTED_CLAUDE_CODE_VERSIONS: tuple[str, ...] = ("2.1.319",)
+"""The Claude Code versions the live contract test passed against. Informational only: nothing compares versions."""
+
+CompatibilityFeature = Literal["messaging", "scratchpad", "liveness"]
+
+
+@dataclass(frozen=True, slots=True)
+class Compatibility:
+    """The result of :func:`check_compatibility`."""
+
+    compatible: bool
+    """``True`` when every feature is aligned."""
+    features: Mapping[CompatibilityFeature, bool]
+    """For each feature, whether the session's record provides what the feature needs."""
+    reasons: tuple[str, ...]
+    """One sentence for each problem found, prefixed with the feature name. Empty when ``compatible`` is ``True``."""
+
+
+def _nonempty_str(value: Any) -> bool:
+    return isinstance(value, str) and bool(value)
+
+
+def _int(value: Any) -> bool:
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def _messaging(raw: Mapping[str, Any]) -> list[str]:
+    reasons = []
+    protocol = raw.get("peerProtocol")
+    supported = ", ".join(map(str, sorted(SUPPORTED_PEER_PROTOCOLS)))
+    if protocol is None:
+        reasons.append(f"messaging: the record has no peerProtocol, and this cc-blackbox version speaks {supported}.")
+    elif not _int(protocol) or protocol not in SUPPORTED_PEER_PROTOCOLS:
+        reasons.append(
+            f"messaging: the session speaks peerProtocol {protocol!r}, and this cc-blackbox version speaks "
+            f"{supported}. Upgrade cc-blackbox."
+        )
+    if not _nonempty_str(raw.get("messagingSocketPath")):
+        reasons.append("messaging: the record has no messagingSocketPath, so the session has messaging turned off.")
+    return reasons
+
+
+def _scratchpad(raw: Mapping[str, Any]) -> list[str]:
+    reasons = []
+    if not _nonempty_str(raw.get("sessionId")):
+        reasons.append("scratchpad: the record has no sessionId string.")
+    cwd = raw.get("cwd")
+    if not _nonempty_str(cwd) or cwd == "?":
+        reasons.append("scratchpad: the record has no cwd string.")
+    return reasons
+
+
+def _liveness(raw: Mapping[str, Any]) -> list[str]:
+    reasons = []
+    if not _int(raw.get("pid")):
+        reasons.append("liveness: the record has no integer pid.")
+    if sys.platform.startswith("linux") and not _nonempty_str(raw.get("procStart")):
+        reasons.append("liveness: the record has no procStart string, so a reused pid cannot be detected.")
+    return reasons
+
+
+def check_compatibility(session: ActiveSession) -> Compatibility:
+    """Check whether ``session``'s record provides what each feature of this package needs.
+
+    - ``messaging`` needs a ``peerProtocol`` in :data:`SUPPORTED_PEER_PROTOCOLS` and a ``messagingSocketPath``.
+    - ``scratchpad`` needs ``sessionId`` and ``cwd`` strings.
+    - ``liveness`` needs an integer ``pid``, and on Linux a ``procStart`` string.
+
+    The Claude Code version in the record is not considered.
+    """
+    raw = session.raw
+    checks: dict[CompatibilityFeature, list[str]] = {
+        "messaging": _messaging(raw),
+        "scratchpad": _scratchpad(raw),
+        "liveness": _liveness(raw),
+    }
+    reasons = tuple(reason for found in checks.values() for reason in found)
+    return Compatibility(
+        compatible=not reasons,
+        features=MappingProxyType({feature: not found for feature, found in checks.items()}),
+        reasons=reasons,
+    )

cc_blackbox/errors.py

@@ -0,0 +1,66 @@
+"""Exceptions raised by the SDK. Every one of them derives from :class:`ClaudeBlackboxError`."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from cc_blackbox.sessions.active import ActiveSession
+
+__all__ = [
+    "AmbiguousSession",
+    "AuthSwitchConfigError",
+    "ClaudeBlackboxError",
+    "MessageTooLarge",
+    "MessagingError",
+    "MessagingUnavailable",
+    "ProfileNotFound",
+    "SessionGone",
+    "SessionNotFound",
+    "UnsupportedProtocol",
+]
+
+
+class ClaudeBlackboxError(Exception):
+    """Base class for every error the SDK raises."""
+
+
+class ProfileNotFound(ClaudeBlackboxError, LookupError):
+    """No profile has the requested name."""
+
+
+class AuthSwitchConfigError(ClaudeBlackboxError):
+    """The auth-switch config file exists but cannot be read as a YAML mapping."""
+
+
+class SessionNotFound(ClaudeBlackboxError, LookupError):
+    """No active session matches the query."""
+
+
+class AmbiguousSession(ClaudeBlackboxError, LookupError):
+    """More than one active session matches the query. ``candidates`` holds all of them."""
+
+    def __init__(self, message: str, candidates: Sequence[ActiveSession]) -> None:
+        super().__init__(message)
+        self.candidates: tuple[ActiveSession, ...] = tuple(candidates)
+
+
+class MessagingError(ClaudeBlackboxError):
+    """A message or control frame could not be written to a session."""
+
+
+class MessagingUnavailable(MessagingError):
+    """The session cannot receive messages: its record names no socket, or the platform is not supported."""
+
+
+class SessionGone(MessagingError):
+    """Nobody listens on the session's socket, so the session has most likely ended."""
+
+
+class MessageTooLarge(MessagingError, ValueError):
+    """The frame exceeds the receiver's 1 MiB line limit. Nothing was sent."""
+
+
+class UnsupportedProtocol(MessagingError):
+    """The session speaks a peer protocol version this SDK does not know."""

cc_blackbox/messaging/__init__.py

@@ -0,0 +1,21 @@
+"""Claude Code's cross-session messaging: frames, transports and the sending API."""
+
+from cc_blackbox.messaging.client import (
+    MessagingTarget,
+    RateLimitedSender,
+    SentMessage,
+    rename_session,
+    send_message,
+)
+from cc_blackbox.messaging.protocol import Priority, build_envelope, percent_encode_address
+
+__all__ = [
+    "MessagingTarget",
+    "Priority",
+    "RateLimitedSender",
+    "SentMessage",
+    "build_envelope",
+    "percent_encode_address",
+    "rename_session",
+    "send_message",
+]

cc_blackbox/messaging/client.py

@@ -0,0 +1,224 @@
+"""Send messages and renames to running Claude Code sessions."""
+
+from __future__ import annotations
+
+import os
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+from cc_blackbox.compatibility import SUPPORTED_PEER_PROTOCOLS
+from cc_blackbox.errors import MessagingUnavailable, UnsupportedProtocol
+from cc_blackbox.messaging.protocol import (
+    Priority,
+    build_envelope,
+    build_rename_frame,
+    build_user_frame,
+    encode_frame,
+    percent_encode_address,
+)
+from cc_blackbox.messaging.transport import default_transport
+from cc_blackbox.sessions.active import ActiveSession
+
+__all__ = [
+    "MessagingTarget",
+    "RateLimitedSender",
+    "SentMessage",
+    "rename_session",
+    "send_message",
+]
+
+MessagingTarget = ActiveSession | os.PathLike[str] | str
+"""A session from :func:`list_active_sessions`, or the path of a messaging socket."""
+
+
+@dataclass(frozen=True, slots=True)
+class SentMessage:
+    """A frame that was written to a session's socket. Writing it does not mean the model saw it."""
+
+    msg_id: str
+    socket_path: str
+    bytes_written: int
+
+
+def _socket_path(target: MessagingTarget) -> str:
+    if not isinstance(target, ActiveSession):
+        return os.fspath(target)
+    compatibility = target.compatibility
+    if not compatibility.features["messaging"]:
+        reasons = " ".join(r for r in compatibility.reasons if r.startswith("messaging:"))
+        if target.messaging_socket is None and target.peer_protocol in SUPPORTED_PEER_PROTOCOLS:
+            raise MessagingUnavailable(f"The session {target.address} cannot receive messages. {reasons}")
+        raise UnsupportedProtocol(f"The session {target.address} is not compatible with cc-blackbox. {reasons}")
+    assert target.messaging_socket is not None
+    return os.fspath(target.messaging_socket)
+
+
+def send_message(
+    target: MessagingTarget,
+    content: str,
+    *,
+    sender: str,
+    sender_name: str | None = None,
+    priority: Priority = "next",
+    msg_id: str | None = None,
+    timeout: float = 5.0,
+) -> SentMessage:
+    """Deliver ``content`` to a running session as a message from another Claude session.
+
+    The receiving model sees the text after a header saying another Claude session sent it, and before a footer
+    saying it did not come from the user. Delivery is best effort. The receiver accepts the frame without answering,
+    and may then:
+
+    - drop it when ``sender`` exceeds 30 messages in a burst or 1 message per 2 seconds sustained,
+    - drop it when the same content arrived within the last 30 seconds, so put a sequence number or time into it,
+    - drop it when 50 messages already wait in its queue,
+    - hold it until the user approves it, which a session in bypass-permissions mode does by default.
+
+    ``sender`` goes into the frame's ``from`` field. The model never sees it; the receiver uses it as the key of its
+    rate limit and duplicate check, so give every independent sending process its own label. With ``sender_name``,
+    the content is wrapped in a ``<cross-session-message from="did:<sender>" from-name="<sender_name>">`` envelope
+    (see :func:`build_envelope`), and the receiver's terminal shows the message under that name. Without it, the
+    content arrives as it is and the model does not learn who sent it.
+
+    A ``target`` that is an :class:`ActiveSession` must be aligned for messaging (see :func:`check_compatibility`);
+    its Claude Code version does not matter. A path is used as it is.
+
+    Raises:
+        MessagingUnavailable: the session has messaging turned off, or the platform is Windows.
+        UnsupportedProtocol: the session's messaging is not aligned with this package, see
+            :func:`check_compatibility`. The message lists the reasons.
+        MessageTooLarge: the frame exceeds 1 MiB; nothing was sent.
+        SessionGone: nobody listens on the socket.
+        MessagingError: any other failure to write.
+        ValueError: an argument is empty or malformed.
+    """
+    socket_path = _socket_path(target)
+    if sender_name is not None:
+        content = build_envelope(content, from_address=f"did:{percent_encode_address(sender)}", from_name=sender_name)
+    frame = build_user_frame(content, sender=sender, priority=priority, msg_id=msg_id)
+    payload = encode_frame(frame)
+    default_transport().send(socket_path, payload, timeout=timeout)
+    return SentMessage(msg_id=frame["msg_id"], socket_path=socket_path, bytes_written=len(payload))
+
+
+def rename_session(target: MessagingTarget, name: str, *, timeout: float = 5.0) -> None:
+    """Ask a running session to rename itself to ``name``.
+
+    The session may still change the name: when another live session in its profile already holds the name, Claude
+    Code gives the newcomer a different one. Read the session's record again to see the result.
+
+    Raises:
+        The same errors as :func:`send_message`.
+    """
+    socket_path = _socket_path(target)
+    default_transport().send(socket_path, encode_frame(build_rename_frame(name)), timeout=timeout)
+
+
+@dataclass(slots=True)
+class _Bucket:
+    tokens: float
+    updated: float
+    pending: list[str] = field(default_factory=list)
+
+
+class RateLimitedSender:
+    """Send messages under a client-side rate limit that stays below the receiver's.
+
+    The receiver drops messages above 30 in a burst or 1 per 2 seconds for each ``from`` label, and it does not tell
+    the sender. This class keeps a token bucket for each target socket, 25 messages refilled at 0.4 per second by
+    default. When the bucket is empty, :meth:`send` queues the message. The next call that finds a token, from
+    :meth:`send` or :meth:`flush`, sends every queued message for that target as one message, joined by ``separator``.
+    Coalescing also keeps a burst of identical texts from being dropped by the receiver's duplicate check.
+
+    A queued message is lost when sending it fails. Instances are thread-safe.
+    """
+
+    def __init__(
+        self,
+        sender: str,
+        *,
+        sender_name: str | None = None,
+        capacity: int = 25,
+        refill_per_second: float = 0.4,
+        priority: Priority = "next",
+        timeout: float = 5.0,
+        separator: str = "\n\n",
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        if capacity < 1 or refill_per_second <= 0:
+            raise ValueError("The capacity must be at least 1 and the refill rate must be positive.")
+        self.sender = sender
+        self.sender_name = sender_name
+        self.capacity = capacity
+        self.refill_per_second = refill_per_second
+        self.priority: Priority = priority
+        self.timeout = timeout
+        self.separator = separator
+        self._clock = clock
+        self._buckets: dict[str, _Bucket] = {}
+        self._lock = threading.Lock()
+
+    def _bucket(self, socket_path: str) -> _Bucket:
+        now = self._clock()
+        bucket = self._buckets.get(socket_path)
+        if bucket is None:
+            bucket = self._buckets[socket_path] = _Bucket(tokens=float(self.capacity), updated=now)
+        else:
+            bucket.tokens = min(float(self.capacity), bucket.tokens + (now - bucket.updated) * self.refill_per_second)
+            bucket.updated = now
+        return bucket
+
+    def _drain(self, socket_path: str, bucket: _Bucket) -> SentMessage | None:
+        if not bucket.pending or bucket.tokens < 1:
+            return None
+        content = self.separator.join(bucket.pending)
+        bucket.pending.clear()
+        bucket.tokens -= 1
+        return send_message(
+            socket_path,
+            content,
+            sender=self.sender,
+            sender_name=self.sender_name,
+            priority=self.priority,
+            timeout=self.timeout,
+        )
+
+    def send(self, target: MessagingTarget, content: str) -> SentMessage | None:
+        """Send ``content`` now, together with anything queued for the target, or queue it when no token is left.
+
+        Returns the sent message, or ``None`` when ``content`` was queued.
+
+        Raises:
+            The errors of :func:`send_message`. The target checks run before anything is queued.
+        """
+        if not content:
+            raise ValueError("The message content is empty. The receiver drops empty messages.")
+        socket_path = _socket_path(target)
+        with self._lock:
+            bucket = self._bucket(socket_path)
+            bucket.pending.append(content)
+            return self._drain(socket_path, bucket)
+
+    def flush(self) -> list[SentMessage]:
+        """Send the queued messages of every target that has a token, and return what was sent."""
+        sent: list[SentMessage] = []
+        with self._lock:
+            for socket_path in list(self._buckets):
+                message = self._drain(socket_path, self._bucket(socket_path))
+                if message is not None:
+                    sent.append(message)
+        return sent
+
+    def pending_count(self, target: MessagingTarget) -> int:
+        """Return how many messages wait for a token for ``target``."""
+        with self._lock:
+            bucket = self._buckets.get(_socket_path(target))
+            return len(bucket.pending) if bucket is not None else 0
+
+    def seconds_until_next_token(self, target: MessagingTarget) -> float:
+        """Return how long the next message to ``target`` would wait for a token; 0 when one is available."""
+        with self._lock:
+            bucket = self._bucket(_socket_path(target))
+            return max(0.0, (1 - bucket.tokens) / self.refill_per_second)

cc_blackbox/messaging/protocol.py

@@ -0,0 +1,164 @@
+"""Frames of Claude Code's cross-session messaging protocol (peer protocol 1).
+
+A frame is one JSON object on one ``\\n``-terminated line. The receiver never answers on the same connection.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import unicodedata
+import uuid
+from typing import Any, Literal
+
+from cc_blackbox.errors import MessageTooLarge
+
+__all__ = [
+    "ENVELOPE_TAG",
+    "MAX_LINE_LENGTH",
+    "Priority",
+    "build_envelope",
+    "build_rename_frame",
+    "build_user_frame",
+    "encode_frame",
+    "percent_encode_address",
+]
+
+Priority = Literal["now", "next", "later"]
+"""Where the receiver queues a message. ``now`` jumps ahead of queued work, ``later`` waits behind it."""
+
+MAX_LINE_LENGTH = 1_048_576
+"""The receiver drops the connection when one line exceeds this many UTF-16 code units."""
+
+ENVELOPE_TAG = "cross-session-message"
+
+_PRIORITIES = ("now", "next", "later")
+_UUID = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.IGNORECASE)
+_ADDRESS = re.compile(r"[A-Za-z0-9%:_/.\\-]+")
+_ADDRESS_SAFE = re.compile(r"[A-Za-z0-9:_/.\\-]")
+# The receiver escapes an opener or closer of these tags inside a peer message body, so a body can never end the
+# envelope early or open a nested one. ASCII only: Claude Code also catches Unicode look-alikes of "<", "/" and of
+# the tag names, and escapes those on its side.
+_NESTED_TAG = re.compile(
+    r"<(?!\\)(?=[^A-Za-z0-9_\-<>]*(?:cross-session-message|teammate-message|agent-message)(?:[^A-Za-z0-9_\-]|$))",
+    re.IGNORECASE,
+)
+_NAME_REMOVED_CATEGORIES = ("Cf", "Cc", "Cs", "Zl", "Zp")
+_NAME_MAX_CODE_POINTS = 64
+_JS_TRIM = "\t\n\v\f\r \u00a0\u1680" + "".join(map(chr, range(0x2000, 0x200B))) + "\u2028\u2029\u202f\u205f\u3000\ufeff"
+
+
+def percent_encode_address(value: str) -> str:
+    """Percent-encode ``value`` for the ``from`` attribute the way Claude Code encodes socket paths.
+
+    Every character outside ``[A-Za-z0-9:_/.\\-]`` becomes its UTF-8 bytes as uppercase ``%XX``.
+    """
+    return "".join(
+        ch if _ADDRESS_SAFE.fullmatch(ch) else "".join(f"%{b:02X}" for b in ch.encode("utf-8", "surrogatepass"))
+        for ch in value
+    )
+
+
+def _envelope_name(name: str) -> str:
+    # Claude Code's sanitizer: drop `"<>`, drop format, control, surrogate and line/paragraph separator characters,
+    # trim, cap at 64 code points. Claude Code appends an ellipsis after 64 code points, which the receiver's own
+    # round-trip check then rejects; cutting to 63 plus the ellipsis keeps the name within the limit so it survives.
+    text = re.sub(r'["<>]', "", name)
+    text = "".join(ch for ch in text if unicodedata.category(ch) not in _NAME_REMOVED_CATEGORIES).strip(_JS_TRIM)
+    if len(text) > _NAME_MAX_CODE_POINTS:
+        text = text[: _NAME_MAX_CODE_POINTS - 1] + "\u2026"
+    return text
+
+
+def escape_envelope_body(body: str) -> str:
+    """Escape every ``<cross-session-message``, ``<teammate-message`` and ``<agent-message`` opener or closer in
+    ``body`` as ``<\\...``, the way Claude Code's own sender does. Already escaped text is left alone."""
+    return _NESTED_TAG.sub("<\\\\", body)
+
+
+def build_envelope(body: str, *, from_address: str, from_name: str | None = None) -> str:
+    """Wrap ``body`` in a ``<cross-session-message>`` envelope, byte for byte as Claude Code's own sender does.
+
+    The receiver's terminal then shows the message as a peer message under ``from_name``, and the model sees
+    ``from_address`` as the address to reply to. ``from_address`` must be a ``scheme:value`` address made of
+    ``[A-Za-z0-9%:_/.\\-]``; :func:`percent_encode_address` makes any value fit. Use ``did:<label>`` for a sender that
+    cannot receive replies, and never the address of another session: the receiver does not verify it. ``from_name``
+    is cleaned the way Claude Code cleans it and is left out when nothing remains.
+
+    The ``from-session``, ``hop-chain`` and ``from-mode`` attributes are never written. ``from-mode`` in particular
+    would be a claim about the sender's permission mode.
+
+    Raises:
+        ValueError: ``from_address`` contains a character the receiver does not accept.
+    """
+    if not _ADDRESS.fullmatch(from_address):
+        raise ValueError(
+            f"The envelope address {from_address!r} may contain only letters, digits and %:_/.\\- characters. "
+            "Use percent_encode_address() on the variable part."
+        )
+    attributes = f' from="{from_address}"'
+    name = _envelope_name(from_name) if from_name is not None else ""
+    if name:
+        attributes += f' from-name="{name}"'
+    return f"<{ENVELOPE_TAG}{attributes}>\n{escape_envelope_body(body)}\n</{ENVELOPE_TAG}>"
+
+
+def build_user_frame(
+    content: str, *, sender: str, priority: Priority = "next", msg_id: str | None = None
+) -> dict[str, Any]:
+    """Build the frame that delivers ``content`` as a peer message.
+
+    ``sender`` goes into the JSON ``from`` field. The receiver never shows it to the model, but uses it as the key of
+    its rate limit and its 30-second duplicate check, and shows it to the user when it holds the message for approval.
+    ``msg_id`` must be a UUID; the receiver ignores any other value. It defaults to a random UUID.
+
+    The frame never carries ``session_id``: a value that differs from the receiver's makes it drop the message
+    without telling anyone.
+
+    Raises:
+        ValueError: ``content`` or ``sender`` is empty, or ``priority`` or ``msg_id`` is not valid.
+    """
+    if not content:
+        raise ValueError("The message content is empty. The receiver drops empty messages.")
+    if not sender:
+        raise ValueError("The sender label is empty. Pass a stable label that identifies the sending tool.")
+    if priority not in _PRIORITIES:
+        raise ValueError(f"The priority {priority!r} is not one of now, next or later.")
+    if msg_id is None:
+        msg_id = str(uuid.uuid4())
+    elif not _UUID.fullmatch(msg_id):
+        raise ValueError(f"The msg_id {msg_id!r} is not a UUID such as {uuid.uuid4()}. The receiver ignores it.")
+    return {
+        "type": "user",
+        "from": sender,
+        "priority": priority,
+        "msg_id": msg_id,
+        "message": {"role": "user", "content": content},
+    }
+
+
+def build_rename_frame(name: str) -> dict[str, Any]:
+    """Build the control frame that renames the receiving session to ``name``.
+
+    Raises:
+        ValueError: ``name`` is empty.
+    """
+    if not name:
+        raise ValueError("The new session name is empty.")
+    return {"type": "control", "action": "rename", "name": name}
+
+
+def encode_frame(frame: dict[str, Any]) -> bytes:
+    """Serialise ``frame`` as one UTF-8 JSON line, newline included.
+
+    Raises:
+        MessageTooLarge: the line exceeds :data:`MAX_LINE_LENGTH`, so the receiver would drop it.
+    """
+    line = json.dumps(frame, ensure_ascii=False, separators=(",", ":"))
+    length = len(line.encode("utf-16-le", "surrogatepass")) // 2 + 1
+    if length > MAX_LINE_LENGTH:
+        raise MessageTooLarge(
+            f"The frame is {length} characters long and the receiver accepts at most {MAX_LINE_LENGTH}. "
+            "Shorten the message or split it."
+        )
+    return (line + "\n").encode("utf-8", "surrogatepass")