agent-protocols 0.1.0__tar.gz → 0.2.2__tar.gz

{agent_protocols-0.1.0 → agent_protocols-0.2.2}/PKG-INFO

@@ -1,13 +1,12 @@
 Metadata-Version: 2.4
 Name: agent-protocols
-Version: 0.1.0
+Version: 0.2.2
 Summary: Python SDK for Agent Identity, Agent Profile, and Agent Discourse protocols
 Author: LDCLabs
 License: MIT
 Keywords: agent,protocol,ed25519,sdk
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
-Requires-Dist: base58<3,>=2.1
 Requires-Dist: cryptography>=42
 Requires-Dist: rfc8785<0.2,>=0.1.4
 Provides-Extra: http
@@ -19,22 +18,23 @@ Python SDK for the draft Agent Identity, Agent Profile, and Agent Discourse prot
 
 ## Modules
 
-- `agent_protocols.identity`: `did:agent:` encoding, JCS canonicalization, event IDs, Ed25519 signing and verification, live-write nonce checks, request JWT helpers.
+- `agent_protocols.identity`: `did:agent:` encoding, JCS canonicalization, event hashes, Ed25519 signing and verification, live-write nonce checks, request JWT helpers.
 - `agent_protocols.profile`: `profile.update` payload helpers, validation, materialization.
-- `agent_protocols.discourse`: ADP event constants, room helpers, room-path checks, permission and state helpers.
+- `agent_protocols.discourse`: ADP event constants, join request helpers, room-path checks, permission and state helpers.
 - `agent_protocols.http_client`: optional requests-based Profile and Discourse clients. Install with `agent-protocols[http]`.
 
 ## Example
 
 ```python
-from agent_protocols import AgentSigner, materialize_profile, profile_update_event, unix_time_millis
+from agent_protocols import AgentSigner, ClientNonceManager, materialize_profile, profile_update_event, unix_ms
 
 signer = AgentSigner.generate()
+nonces = ClientNonceManager()
 event = profile_update_event(
     signer.agent_id(),
-    unix_time_millis(),
-    "n_01J8Z6",
-    {"agent_id": signer.agent_id(), "name": "ResearchAgent-v3"},
+    unix_ms(),
+    nonces.next_nonce(),
+    {"id": signer.agent_id(), "name": "ResearchAgent-v3"},
 )
 envelope = signer.sign_event(event)
 profile = materialize_profile(envelope)

{agent_protocols-0.1.0 → agent_protocols-0.2.2}/README.md

@@ -4,22 +4,23 @@ Python SDK for the draft Agent Identity, Agent Profile, and Agent Discourse prot
 
 ## Modules
 
-- `agent_protocols.identity`: `did:agent:` encoding, JCS canonicalization, event IDs, Ed25519 signing and verification, live-write nonce checks, request JWT helpers.
+- `agent_protocols.identity`: `did:agent:` encoding, JCS canonicalization, event hashes, Ed25519 signing and verification, live-write nonce checks, request JWT helpers.
 - `agent_protocols.profile`: `profile.update` payload helpers, validation, materialization.
-- `agent_protocols.discourse`: ADP event constants, room helpers, room-path checks, permission and state helpers.
+- `agent_protocols.discourse`: ADP event constants, join request helpers, room-path checks, permission and state helpers.
 - `agent_protocols.http_client`: optional requests-based Profile and Discourse clients. Install with `agent-protocols[http]`.
 
 ## Example
 
 ```python
-from agent_protocols import AgentSigner, materialize_profile, profile_update_event, unix_time_millis
+from agent_protocols import AgentSigner, ClientNonceManager, materialize_profile, profile_update_event, unix_ms
 
 signer = AgentSigner.generate()
+nonces = ClientNonceManager()
 event = profile_update_event(
     signer.agent_id(),
-    unix_time_millis(),
-    "n_01J8Z6",
-    {"agent_id": signer.agent_id(), "name": "ResearchAgent-v3"},
+    unix_ms(),
+    nonces.next_nonce(),
+    {"id": signer.agent_id(), "name": "ResearchAgent-v3"},
 )
 envelope = signer.sign_event(event)
 profile = materialize_profile(envelope)

{agent_protocols-0.1.0 → agent_protocols-0.2.2}/pyproject.toml

@@ -1,13 +1,13 @@
 [project]
 name = "agent-protocols"
-version = "0.1.0"
+version = "0.2.2"
 description = "Python SDK for Agent Identity, Agent Profile, and Agent Discourse protocols"
 readme = "README.md"
 requires-python = ">=3.10"
 license = { text = "MIT" }
 authors = [{ name = "LDCLabs" }]
 keywords = ["agent", "protocol", "ed25519", "sdk"]
-dependencies = ["base58>=2.1,<3", "cryptography>=42", "rfc8785>=0.1.4,<0.2"]
+dependencies = ["cryptography>=42", "rfc8785>=0.1.4,<0.2"]
 
 [project.optional-dependencies]
 http = ["requests>=2.31,<3"]

{agent_protocols-0.1.0 → agent_protocols-0.2.2}/src/agent_protocols/__init__.py

@@ -1,26 +1,26 @@
 from .errors import AgentProtocolError
 from .identity import (
     AGENT_ID_PREFIX,
-    EVENT_ID_PREFIX,
     AgentSigner,
+    ClientNonceManager,
+    MAX_NONCE_HEADER,
     MemoryNonceStore,
     RequestBinding,
     agent_id_from_public_key,
     canonical_event_bytes,
     create_event,
     create_request_jwt_claims,
-    event_id,
+    event_hash,
     public_key_bytes,
-    random_nonce,
     sign_event,
-    unix_time_millis,
-    unix_time_secs,
+    unix_ms,
+    unix_secs,
     validate_agent_id,
+    validate_nonce,
     verify_envelope,
-    verify_event_id,
+    verify_event_hash,
     verify_live_envelope,
     verify_request_jwt,
-    verify_request_jwt_live,
     verify_signature,
     verify_timestamp,
     with_room_id,
@@ -29,32 +29,32 @@ from .profile import PROFILE_PROTOCOL, PROFILE_UPDATE, materialize_profile, prof
 
 __all__ = [
     "AGENT_ID_PREFIX",
-    "EVENT_ID_PREFIX",
+    "MAX_NONCE_HEADER",
     "PROFILE_PROTOCOL",
     "PROFILE_UPDATE",
     "AgentProtocolError",
     "AgentSigner",
+    "ClientNonceManager",
     "MemoryNonceStore",
     "RequestBinding",
     "agent_id_from_public_key",
     "canonical_event_bytes",
     "create_event",
     "create_request_jwt_claims",
-    "event_id",
+    "event_hash",
     "materialize_profile",
     "profile_update_event",
     "public_key_bytes",
-    "random_nonce",
     "sign_event",
-    "unix_time_millis",
-    "unix_time_secs",
+    "unix_ms",
+    "unix_secs",
     "validate_agent_id",
+    "validate_nonce",
     "validate_profile_update",
     "verify_envelope",
-    "verify_event_id",
+    "verify_event_hash",
     "verify_live_envelope",
     "verify_request_jwt",
-    "verify_request_jwt_live",
     "verify_signature",
     "verify_timestamp",
     "with_room_id",

agent_protocols-0.2.2/src/agent_protocols/discourse.py

@@ -0,0 +1,319 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+from typing import Any, Literal, TypedDict
+
+import rfc8785
+
+from .errors import AgentProtocolError
+from .identity import AgentId, Envelope, Event, create_event, verify_envelope, with_room_id
+
+DISCOURSE_PROTOCOL = "agent-discourse/1.0"
+
+ROOM_CREATE = "room.create"
+ROOM_JOIN = "room.join"
+ROOM_JOIN_REVIEW = "room.join.review"
+ROOM_LEAVE = "room.leave"
+ROOM_MEMBER_ROLE_UPDATE = "room.member.role.update"
+ROOM_CLOSE = "room.close"
+ROOM_CANCEL = "room.cancel"
+MESSAGE_CREATE = "message.create"
+REACTION_CREATE = "reaction.create"
+MESSAGE_PROPOSAL_CREATE = "message.proposal.create"
+MESSAGE_POLL_CREATE = "message.poll.create"
+MESSAGE_POLL_VOTE = "message.poll.vote"
+MESSAGE_RESOLUTION_CREATE = "message.resolution.create"
+SOURCE_ADD = "source.add"
+TURN_UPDATE = "turn.update"
+QUESTION_CREATE = "question.create"
+ROOM_STEER = "room.steer"
+MAP_UPDATE = "map.update"
+ARTIFACT_CREATE = "artifact.create"
+
+KNOWN_EVENT_TYPES = {
+    ROOM_CREATE,
+    ROOM_JOIN,
+    ROOM_JOIN_REVIEW,
+    ROOM_LEAVE,
+    ROOM_MEMBER_ROLE_UPDATE,
+    ROOM_CLOSE,
+    ROOM_CANCEL,
+    MESSAGE_CREATE,
+    REACTION_CREATE,
+    MESSAGE_PROPOSAL_CREATE,
+    MESSAGE_POLL_CREATE,
+    MESSAGE_POLL_VOTE,
+    MESSAGE_RESOLUTION_CREATE,
+    SOURCE_ADD,
+    TURN_UPDATE,
+    QUESTION_CREATE,
+    ROOM_STEER,
+    MAP_UPDATE,
+    ARTIFACT_CREATE,
+}
+
+RoomState = Literal["scheduled", "active", "ended", "cancelled"]
+Role = Literal["moderator", "expert", "participant", "observer"]
+JoinRequestStatus = Literal["pending", "approved", "rejected", "expired"]
+
+
+class PermissionContext(TypedDict, total=False):
+    role: Role
+    is_creator: bool
+    join_request_approved: bool
+    moderator_authorized: bool
+    expert_policy_allowed: bool
+    participant_policy_allowed: bool
+    observer_steering_allowed: bool
+    observer_poll_vote_allowed: bool
+
+
+def room_create_event(actor: AgentId, created_at: int, nonce: int, payload: dict[str, Any]) -> Event:
+    return create_event(DISCOURSE_PROTOCOL, ROOM_CREATE, actor, created_at, nonce, payload)
+
+
+def discourse_event(event_type: str, actor: AgentId, created_at: int, nonce: int, room_id: str, payload: Any) -> Event:
+    return with_room_id(create_event(DISCOURSE_PROTOCOL, event_type, actor, created_at, nonce, payload), room_id)
+
+
+def validate_discourse_envelope(envelope: Envelope) -> None:
+    verify_envelope(envelope)
+    event = envelope["event"]
+    protocol = event["protocol"]
+    if protocol != DISCOURSE_PROTOCOL:
+        raise AgentProtocolError("invalid_event_protocol", f"expected {DISCOURSE_PROTOCOL}, got {protocol}")
+    if event_requires_room_id(event["type"]) and "room_id" not in event:
+        raise AgentProtocolError("missing_room_id", "event requires a room_id")
+
+
+def validate_room_path(envelope: Envelope, path_room_id: str) -> None:
+    actual = envelope["event"].get("room_id")
+    if actual is None and envelope["event"]["type"] == ROOM_CREATE:
+        return
+    if actual is None:
+        raise AgentProtocolError("missing_room_id", "event requires a room_id")
+    if actual != path_room_id:
+        raise AgentProtocolError("room_id_mismatch", f"expected {path_room_id}, got {actual}")
+
+
+def event_requires_room_id(event_type: str) -> bool:
+    return event_type != ROOM_CREATE
+
+
+def validate_room_create_payload(payload: dict[str, Any]) -> None:
+    if not str(payload.get("topic", "")).strip():
+        raise AgentProtocolError("invalid_room", "room topic must not be empty")
+    if payload.get("start_time", 0) >= payload.get("end_time", 0):
+        raise AgentProtocolError("invalid_room", "start_time must be before end_time")
+    policy = payload.get("policy") or {}
+    max_participants = policy.get("max_participants")
+    if max_participants is not None and (
+        not isinstance(max_participants, int) or max_participants < 1
+    ):
+        raise AgentProtocolError("invalid_room", "max_participants must be a positive integer")
+
+
+def validate_poll_create_payload(payload: dict[str, Any]) -> None:
+    if not str(payload.get("poll_id", "")).strip() or not str(payload.get("question", "")).strip():
+        raise AgentProtocolError("invalid_poll", "poll_id and question are required")
+    options = payload.get("options", [])
+    if len(options) < 2:
+        raise AgentProtocolError("invalid_poll", "poll requires at least two options")
+    option_ids: set[str] = set()
+    for option in options:
+        option_id = str(option.get("id", ""))
+        label = str(option.get("label", ""))
+        if not option_id.strip() or not label.strip():
+            raise AgentProtocolError("invalid_poll", "option id and label are required")
+        if option_id in option_ids:
+            raise AgentProtocolError("invalid_poll", "poll option ids must be unique")
+        option_ids.add(option_id)
+    min_choices = payload.get("min_choices", 1)
+    max_choices = payload.get("max_choices", 1)
+    if min_choices < 1 or max_choices < min_choices:
+        raise AgentProtocolError("invalid_poll", "invalid poll choice limits")
+
+
+def validate_poll_vote_payload(payload: dict[str, Any], poll: dict[str, Any], now_ms: int | None = None) -> None:
+    if poll.get("closes_at") is not None and now_ms is not None and now_ms > poll["closes_at"]:
+        raise AgentProtocolError("poll_closed", "poll is closed")
+    min_choices = poll.get("min_choices", 1)
+    max_choices = poll.get("max_choices", 1)
+    option_ids = {option["id"] for option in poll.get("options", [])}
+    selected = payload.get("option_ids", [])
+    selected_set = set(selected)
+    if len(selected_set) != len(selected):
+        raise AgentProtocolError("invalid_poll_vote", "duplicate poll options")
+    if len(selected_set) < min_choices or len(selected_set) > max_choices:
+        raise AgentProtocolError("invalid_poll_vote", "invalid number of options")
+    if any(option_id not in option_ids for option_id in selected_set):
+        raise AgentProtocolError("invalid_poll_vote", "unknown poll option")
+
+
+def server_record_hash_payload(
+    room_id: str,
+    seq: int,
+    pre_hash: str | None,
+    envelope_hash: str,
+    received_at: int,
+) -> dict[str, Any]:
+    return {
+        "room_id": room_id,
+        "seq": seq,
+        "pre_hash": pre_hash,
+        "envelope_hash": envelope_hash,
+        "received_at": received_at,
+    }
+
+
+def server_record_hash(
+    room_id: str,
+    seq: int,
+    pre_hash: str | None,
+    envelope_hash: str,
+    received_at: int,
+) -> str:
+    return _hash_canonical_json(server_record_hash_payload(room_id, seq, pre_hash, envelope_hash, received_at))
+
+
+def build_server_record(
+    room_id: str,
+    seq: int,
+    pre_hash: str | None,
+    received_at: int,
+    envelope: Envelope,
+) -> dict[str, Any]:
+    return {
+        "room_id": room_id,
+        "seq": seq,
+        "pre_hash": pre_hash,
+        "hash": server_record_hash(room_id, seq, pre_hash, envelope["hash"], received_at),
+        "received_at": received_at,
+        "envelope": envelope,
+    }
+
+
+def verify_server_record(record: dict[str, Any]) -> None:
+    expected = server_record_hash(
+        record["room_id"],
+        record["seq"],
+        record.get("pre_hash"),
+        record["envelope"]["hash"],
+        record["received_at"],
+    )
+    if record["hash"] != expected:
+        raise AgentProtocolError("invalid_record_hash", f"invalid server record hash: expected {expected}, got {record['hash']}")
+
+
+def verify_server_record_chain(records: list[dict[str, Any]]) -> None:
+    previous: dict[str, Any] | None = None
+    for record in records:
+        verify_server_record(record)
+        if previous is None:
+            if record["seq"] != 1:
+                raise AgentProtocolError("invalid_record_chain", "first seq must be 1")
+            if record.get("pre_hash") is not None:
+                raise AgentProtocolError("invalid_record_chain", "first pre_hash must be null")
+        else:
+            if record["seq"] != previous["seq"] + 1:
+                raise AgentProtocolError("invalid_record_chain", "seq must increase by 1")
+            if record.get("pre_hash") != previous["hash"]:
+                raise AgentProtocolError("invalid_record_chain", "pre_hash mismatch")
+        previous = record
+
+
+def archive_events_digest(records: list[dict[str, Any]]) -> str:
+    return _hash_canonical_json(records)
+
+
+def can_submit_event(event_type: str, context: PermissionContext) -> bool:
+    if event_type == ROOM_CREATE:
+        return True
+    if event_type == ROOM_JOIN:
+        return context.get("join_request_approved", False)
+    if context.get("is_creator"):
+        return event_type in KNOWN_EVENT_TYPES
+
+    role = context.get("role")
+    if role == "moderator":
+        return _moderator_can_submit(event_type, context.get("moderator_authorized", False))
+    if role == "expert":
+        return _speaker_can_submit(event_type, context.get("expert_policy_allowed", False))
+    if role == "participant":
+        return _speaker_can_submit(event_type, context.get("participant_policy_allowed", False))
+    if role == "observer":
+        return _observer_can_submit(event_type, context)
+    return False
+
+
+def can_write_in_state(event_type: str, state: RoomState, *, post_end_reaction_allowed: bool = False) -> bool:
+    if state == "scheduled":
+        return event_type in {ROOM_JOIN, ROOM_JOIN_REVIEW, ROOM_CANCEL}
+    if state == "active":
+        return event_type not in {ROOM_CREATE, ROOM_CANCEL}
+    if state == "ended":
+        return post_end_reaction_allowed and event_type == REACTION_CREATE
+    if state == "cancelled":
+        return False
+    return False
+
+
+def can_accept_room_write(event_type: str, state: RoomState, context: PermissionContext, *, post_end_reaction_allowed: bool = False) -> bool:
+    return can_submit_event(event_type, context) and can_write_in_state(event_type, state, post_end_reaction_allowed=post_end_reaction_allowed)
+
+
+def validate_room_write(event_type: str, state: RoomState, context: PermissionContext, *, post_end_reaction_allowed: bool = False) -> None:
+    if not can_accept_room_write(event_type, state, context, post_end_reaction_allowed=post_end_reaction_allowed):
+        raise AgentProtocolError("permission_denied", "actor lacks permission or state is not writable")
+
+
+def _moderator_can_submit(event_type: str, moderator_authorized: bool) -> bool:
+    allowed = {
+        ROOM_JOIN_REVIEW,
+        ROOM_CLOSE,
+        MESSAGE_CREATE,
+        SOURCE_ADD,
+        TURN_UPDATE,
+        QUESTION_CREATE,
+        ROOM_STEER,
+        MAP_UPDATE,
+        ARTIFACT_CREATE,
+        MESSAGE_PROPOSAL_CREATE,
+        MESSAGE_POLL_CREATE,
+        MESSAGE_POLL_VOTE,
+        MESSAGE_RESOLUTION_CREATE,
+        REACTION_CREATE,
+        ROOM_LEAVE,
+    }
+    return event_type in allowed or (moderator_authorized and event_type in {ROOM_MEMBER_ROLE_UPDATE, ROOM_CANCEL})
+
+
+def _speaker_can_submit(event_type: str, policy_allowed: bool) -> bool:
+    allowed = {
+        MESSAGE_CREATE,
+        SOURCE_ADD,
+        ROOM_STEER,
+        MESSAGE_PROPOSAL_CREATE,
+        MESSAGE_POLL_CREATE,
+        MESSAGE_POLL_VOTE,
+        REACTION_CREATE,
+        ROOM_LEAVE,
+    }
+    policy_events = {QUESTION_CREATE, MAP_UPDATE, ARTIFACT_CREATE, MESSAGE_RESOLUTION_CREATE}
+    return event_type in allowed or (policy_allowed and event_type in policy_events)
+
+
+def _observer_can_submit(event_type: str, context: PermissionContext) -> bool:
+    return (
+        event_type in {REACTION_CREATE, ROOM_LEAVE}
+        or (context.get("observer_steering_allowed", False) and event_type == ROOM_STEER)
+        or (context.get("observer_poll_vote_allowed", False) and event_type == MESSAGE_POLL_VOTE)
+    )
+
+
+def _hash_canonical_json(value: Any) -> str:
+    canonical = rfc8785.dumps(value)
+    data = canonical if isinstance(canonical, bytes) else canonical.encode()
+    digest = hashlib.sha3_256(data).digest()
+    return base64.urlsafe_b64encode(digest).rstrip(b"=").decode()

agent_protocols-0.2.2/src/agent_protocols/http_client.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote, urlencode
+
+try:
+    import requests
+except ImportError:  # pragma: no cover
+    requests = None  # type: ignore[assignment]
+
+from .identity import AgentId, Envelope
+
+
+class ProfileClient:
+    def __init__(self, base_url: str, session: Any | None = None):
+        self.base_url = base_url.rstrip("/")
+        self.session = session or _requests_session()
+
+    def get_profile(self, agent_id: AgentId) -> dict[str, Any]:
+        return self._get(f"/v1/profiles/{agent_id}")
+
+    def get_profiles(self, agent_ids: list[AgentId]) -> dict[str, Any]:
+        return self._post("/v1/profiles/batch", {"ids": agent_ids})
+
+    def profile_events(self, agent_id: AgentId, limit: int = 1) -> dict[str, Any]:
+        return self._get(f"/v1/profiles/{agent_id}/events?limit={limit}")
+
+    def submit_profile_update(self, envelope: Envelope) -> dict[str, Any]:
+        return self._post("/v1/profiles", envelope)
+
+    def _get(self, path: str) -> Any:
+        response = self.session.get(self.base_url + path)
+        response.raise_for_status()
+        return response.json()
+
+    def _post(self, path: str, body: Any) -> dict[str, Any]:
+        response = self.session.post(self.base_url + path, json=body)
+        response.raise_for_status()
+        return response.json()
+
+
+class DiscourseClient:
+    def __init__(self, base_url: str, session: Any | None = None):
+        self.base_url = base_url.rstrip("/")
+        self.session = session or _requests_session()
+
+    def protocol(self) -> dict[str, Any]:
+        return self._get("/.well-known/agent-discourse")
+
+    def create_room(self, envelope: Envelope) -> dict[str, Any]:
+        return self._post("/v1/rooms", envelope)
+
+    def room(self, room_id: str) -> dict[str, Any]:
+        return self._get(f"/v1/rooms/{room_id}")
+
+    def request_join(self, room_id: str, jwt: str, request: dict[str, Any]) -> dict[str, Any]:
+        return self._post(f"/v1/rooms/{room_id}/join-requests", request, jwt=jwt)
+
+    def join_request(self, room_id: str, request_id: str, jwt: str) -> dict[str, Any]:
+        return self._get(f"/v1/rooms/{room_id}/join-requests/{request_id}", jwt=jwt)
+
+    def join_requests(self, room_id: str, jwt: str) -> list[dict[str, Any]]:
+        return self._get(f"/v1/rooms/{room_id}/join-requests", jwt=jwt)
+
+    def join_room(self, room_id: str, envelope: Envelope) -> dict[str, Any]:
+        return self._post(f"/v1/rooms/{room_id}", envelope)
+
+    def leave_room(self, room_id: str, envelope: Envelope) -> dict[str, Any]:
+        return self._post(f"/v1/rooms/{room_id}", envelope)
+
+    def submit_event(self, room_id: str, envelope: Envelope) -> dict[str, Any]:
+        return self._post(f"/v1/rooms/{room_id}", envelope)
+
+    def events(
+        self,
+        room_id: str,
+        *,
+        after_seq: int | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+        jwt: str | None = None,
+    ) -> list[dict[str, Any]]:
+        query = urlencode(
+            {
+                key: value
+                for key, value in {
+                    "after_seq": after_seq,
+                    "limit": limit,
+                    "cursor": cursor,
+                }.items()
+                if value is not None
+            }
+        )
+        suffix = f"?{query}" if query else ""
+        return self._get(f"/v1/rooms/{room_id}/events{suffix}", jwt=jwt)
+
+    def websocket_events_url(self, room_id: str, jwt: str) -> str:
+        return websocket_events_url(self.base_url, room_id, jwt)
+
+    def archive(self, room_id: str) -> dict[str, Any]:
+        return self._get(f"/v1/rooms/{room_id}/archive")
+
+    def _get(self, path: str, jwt: str | None = None) -> Any:
+        response = self.session.get(self.base_url + path, headers=_auth_headers(jwt))
+        response.raise_for_status()
+        return response.json()
+
+    def _post(self, path: str, body: Any, jwt: str | None = None) -> Any:
+        response = self.session.post(self.base_url + path, json=body, headers=_auth_headers(jwt))
+        response.raise_for_status()
+        return response.json()
+
+
+def websocket_events_url(base_url: str, room_id: str, jwt: str) -> str:
+    websocket_base = base_url.rstrip("/")
+    if websocket_base.startswith("https://"):
+        websocket_base = "wss://" + websocket_base[len("https://") :]
+    elif websocket_base.startswith("http://"):
+        websocket_base = "ws://" + websocket_base[len("http://") :]
+    return f"{websocket_base}/v1/rooms/{quote(room_id, safe='')}/events/live?access_token={quote(jwt, safe='')}"
+
+
+def _auth_headers(jwt: str | None) -> dict[str, str] | None:
+    return {"Authorization": f"Bearer {jwt}"} if jwt else None
+
+
+def _requests_session() -> Any:
+    if requests is None:
+        raise RuntimeError("Install agent-protocols[http] to use HTTP clients")
+    return requests.Session()