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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-protocols
-Version: 0.2.2
+Version: 0.2.3
 Summary: Python SDK for Agent Identity, Agent Profile, and Agent Discourse protocols
 Author: LDCLabs
 License: MIT
@@ -39,3 +39,5 @@ event = profile_update_event(
 envelope = signer.sign_event(event)
 profile = materialize_profile(envelope)
 ```
+
+`username` is provider-confirmed and appears on Profile documents returned by a profile service. Do not put it in agent-submitted `profile.update` payloads.

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

@@ -25,3 +25,5 @@ event = profile_update_event(
 envelope = signer.sign_event(event)
 profile = materialize_profile(envelope)
 ```
+
+`username` is provider-confirmed and appears on Profile documents returned by a profile service. Do not put it in agent-submitted `profile.update` payloads.

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

@@ -1,6 +1,6 @@
 [project]
 name = "agent-protocols"
-version = "0.2.2"
+version = "0.2.3"
 description = "Python SDK for Agent Identity, Agent Profile, and Agent Discourse protocols"
 readme = "README.md"
 requires-python = ">=3.10"

{agent_protocols-0.2.2 → agent_protocols-0.2.3}/src/agent_protocols/discourse.py

@@ -30,6 +30,10 @@ QUESTION_CREATE = "question.create"
 ROOM_STEER = "room.steer"
 MAP_UPDATE = "map.update"
 ARTIFACT_CREATE = "artifact.create"
+SESSION_OFFER = "session.offer"
+SESSION_ANSWER = "session.answer"
+SESSION_CANDIDATE = "session.candidate"
+SESSION_CLOSE = "session.close"
 
 KNOWN_EVENT_TYPES = {
     ROOM_CREATE,
@@ -51,11 +55,16 @@ KNOWN_EVENT_TYPES = {
     ROOM_STEER,
     MAP_UPDATE,
     ARTIFACT_CREATE,
+    SESSION_OFFER,
+    SESSION_ANSWER,
+    SESSION_CANDIDATE,
+    SESSION_CLOSE,
 }
 
 RoomState = Literal["scheduled", "active", "ended", "cancelled"]
 Role = Literal["moderator", "expert", "participant", "observer"]
 JoinRequestStatus = Literal["pending", "approved", "rejected", "expired"]
+SESSION_MEDIA_KINDS = {"audio", "video", "screen", "data", "file"}
 
 
 class PermissionContext(TypedDict, total=False):
@@ -151,6 +160,36 @@ def validate_poll_vote_payload(payload: dict[str, Any], poll: dict[str, Any], no
         raise AgentProtocolError("invalid_poll_vote", "unknown poll option")
 
 
+def validate_session_offer_payload(payload: dict[str, Any]) -> None:
+    _validate_session_id(payload.get("session_id"))
+    if payload.get("session_type") != "webrtc":
+        raise AgentProtocolError("invalid_session", "session_type must be webrtc")
+    media = payload.get("media", [])
+    if not isinstance(media, list) or not media:
+        raise AgentProtocolError("invalid_session", "media must not be empty")
+    if any(media_kind not in SESSION_MEDIA_KINDS for media_kind in media):
+        raise AgentProtocolError("invalid_session", "unsupported media kind")
+    _validate_session_description(payload.get("description"), "offer")
+    _validate_session_transfers(payload.get("transfers", []))
+
+
+def validate_session_answer_payload(payload: dict[str, Any]) -> None:
+    _validate_session_id(payload.get("session_id"))
+    if not str(payload.get("offer_event_id", "")).strip():
+        raise AgentProtocolError("invalid_session", "offer_event_id is required")
+    _validate_session_description(payload.get("description"), "answer")
+    _validate_session_transfers(payload.get("transfers", []))
+
+
+def validate_session_candidate_payload(payload: dict[str, Any]) -> None:
+    _validate_session_id(payload.get("session_id"))
+    if payload.get("end_of_candidates"):
+        return
+    candidate = payload.get("candidate") or {}
+    if not str(candidate.get("candidate", "")).strip():
+        raise AgentProtocolError("invalid_session", "candidate is required unless end_of_candidates is true")
+
+
 def server_record_hash_payload(
     room_id: str,
     seq: int,
@@ -279,6 +318,10 @@ def _moderator_can_submit(event_type: str, moderator_authorized: bool) -> bool:
         ROOM_STEER,
         MAP_UPDATE,
         ARTIFACT_CREATE,
+        SESSION_OFFER,
+        SESSION_ANSWER,
+        SESSION_CANDIDATE,
+        SESSION_CLOSE,
         MESSAGE_PROPOSAL_CREATE,
         MESSAGE_POLL_CREATE,
         MESSAGE_POLL_VOTE,
@@ -297,6 +340,10 @@ def _speaker_can_submit(event_type: str, policy_allowed: bool) -> bool:
         MESSAGE_PROPOSAL_CREATE,
         MESSAGE_POLL_CREATE,
         MESSAGE_POLL_VOTE,
+        SESSION_OFFER,
+        SESSION_ANSWER,
+        SESSION_CANDIDATE,
+        SESSION_CLOSE,
         REACTION_CREATE,
         ROOM_LEAVE,
     }
@@ -312,6 +359,35 @@ def _observer_can_submit(event_type: str, context: PermissionContext) -> bool:
     )
 
 
+def _validate_session_id(session_id: Any) -> None:
+    if not str(session_id or "").strip():
+        raise AgentProtocolError("invalid_session", "session_id is required")
+
+
+def _validate_session_description(description: Any, expected_type: str) -> None:
+    if not isinstance(description, dict):
+        raise AgentProtocolError("invalid_session", "session description is required")
+    if description.get("type") != expected_type:
+        raise AgentProtocolError("invalid_session", f"session description type must be {expected_type}")
+    if not str(description.get("sdp", "")).strip():
+        raise AgentProtocolError("invalid_session", "session description sdp is required")
+
+
+def _validate_session_transfers(transfers: Any) -> None:
+    if transfers is None:
+        return
+    if not isinstance(transfers, list):
+        raise AgentProtocolError("invalid_session", "transfers must be an array")
+    for transfer in transfers:
+        if not isinstance(transfer, dict):
+            raise AgentProtocolError("invalid_session", "transfer must be an object")
+        if not str(transfer.get("transfer_id", "")).strip():
+            raise AgentProtocolError("invalid_session", "transfer_id is required")
+        size_bytes = transfer.get("size_bytes")
+        if size_bytes is not None and (not isinstance(size_bytes, int) or size_bytes < 0):
+            raise AgentProtocolError("invalid_session", "size_bytes must be a non-negative integer")
+
+
 def _hash_canonical_json(value: Any) -> str:
     canonical = rfc8785.dumps(value)
     data = canonical if isinstance(canonical, bytes) else canonical.encode()

{agent_protocols-0.2.2 → agent_protocols-0.2.3}/src/agent_protocols/profile.py

@@ -35,6 +35,7 @@ def materialize_profile(envelope: Envelope) -> AgentProfile:
     return {
         "id": payload_id,
         "name": payload["name"],
+        "username": None,
         "description": payload.get("description"),
         "avatar_url": payload.get("avatar_url"),
         "provider": payload.get("provider"),

{agent_protocols-0.2.2 → agent_protocols-0.2.3}/src/agent_protocols.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-protocols
-Version: 0.2.2
+Version: 0.2.3
 Summary: Python SDK for Agent Identity, Agent Profile, and Agent Discourse protocols
 Author: LDCLabs
 License: MIT
@@ -39,3 +39,5 @@ event = profile_update_event(
 envelope = signer.sign_event(event)
 profile = materialize_profile(envelope)
 ```
+
+`username` is provider-confirmed and appears on Profile documents returned by a profile service. Do not put it in agent-submitted `profile.update` payloads.

{agent_protocols-0.2.2 → agent_protocols-0.2.3}/tests/test_discourse.py

@@ -7,6 +7,8 @@ from agent_protocols.discourse import (
     ROOM_CREATE,
     ROOM_JOIN,
     ROOM_JOIN_REVIEW,
+    SESSION_CANDIDATE,
+    SESSION_OFFER,
     archive_events_digest,
     build_server_record,
     can_accept_room_write,
@@ -18,6 +20,9 @@ from agent_protocols.discourse import (
     validate_discourse_envelope,
     validate_room_create_payload,
     validate_room_path,
+    validate_session_answer_payload,
+    validate_session_candidate_payload,
+    validate_session_offer_payload,
     verify_server_record,
     verify_server_record_chain,
 )
@@ -63,6 +68,8 @@ class DiscourseTests(unittest.TestCase):
         self.assertFalse(can_submit_event(ROOM_JOIN_REVIEW, {"role": "participant"}))
         self.assertFalse(can_submit_event(ROOM_CANCEL, {"role": "moderator"}))
         self.assertTrue(can_submit_event(ROOM_CANCEL, {"role": "moderator", "moderator_authorized": True}))
+        self.assertTrue(can_submit_event(SESSION_OFFER, {"role": "participant"}))
+        self.assertFalse(can_submit_event(SESSION_CANDIDATE, {"role": "observer"}))
         self.assertTrue(can_submit_event(ROOM_CREATE, {}))
 
     def test_applies_state_restrictions(self):
@@ -111,6 +118,45 @@ class DiscourseTests(unittest.TestCase):
                 }
             )
 
+    def test_validates_webrtc_session_payloads(self):
+        offer = {
+            "session_id": "sess_live_review",
+            "session_type": "webrtc",
+            "media": ["audio", "video", "file"],
+            "description": {"type": "offer", "sdp": "v=0\r\n..."},
+            "transfers": [
+                {
+                    "transfer_id": "file_1",
+                    "file_name": "trace.har",
+                    "size_bytes": 1024,
+                    "mime_type": "application/json",
+                    "content_digest": "sha256:abc",
+                }
+            ],
+        }
+
+        validate_session_offer_payload(offer)
+        validate_session_answer_payload(
+            {
+                "session_id": "sess_live_review",
+                "offer_event_id": "evt_offer",
+                "description": {"type": "answer", "sdp": "v=0\r\n..."},
+                "accepted_media": ["audio", "file"],
+            }
+        )
+        validate_session_candidate_payload(
+            {
+                "session_id": "sess_live_review",
+                "candidate": {"candidate": "candidate:1 1 udp 1 127.0.0.1 3478 typ host"},
+            }
+        )
+        validate_session_candidate_payload({"session_id": "sess_live_review", "end_of_candidates": True})
+
+        with self.assertRaisesRegex(Exception, "offer"):
+            validate_session_offer_payload({**offer, "description": {"type": "answer", "sdp": "v=0\r\n..."}})
+        with self.assertRaisesRegex(Exception, "candidate"):
+            validate_session_candidate_payload({"session_id": "sess_live_review"})
+
     def test_builds_and_verifies_server_record_chains(self):
         signer = AgentSigner.from_seed(bytes([18]) * 32)
         envelope1 = signer.sign_event(

{agent_protocols-0.2.2 → agent_protocols-0.2.3}/tests/test_profile.py

@@ -20,11 +20,22 @@ class ProfileTests(unittest.TestCase):
 
         self.assertEqual(profile["id"], signer.agent_id())
         self.assertEqual(profile["name"], "ResearchAgent-v3")
+        self.assertIsNone(profile["username"])
         self.assertEqual(profile["links"], payload["links"])
         self.assertEqual(profile["extra"], payload["extra"])
         self.assertEqual(profile["updated_at"], 1_779_753_600_000)
         self.assertEqual(profile["event_id"], envelope["hash"])
 
+    def test_does_not_materialize_unconfirmed_payload_username(self):
+        signer = AgentSigner.from_seed(bytes([15]) * 32)
+        payload = {"id": signer.agent_id(), "name": "ResearchAgent-v3", "username": "anda"}
+        envelope = signer.sign_event(profile_update_event(signer.agent_id(), 1_779_753_600_002, 1, payload))
+
+        profile = materialize_profile(envelope)
+
+        self.assertEqual(profile["id"], signer.agent_id())
+        self.assertIsNone(profile["username"])
+
     def test_rejects_actor_payload_mismatch(self):
         signer = AgentSigner.from_seed(bytes([12]) * 32)
         other = AgentSigner.from_seed(bytes([13]) * 32)