agent-protocols 0.3.1__tar.gz → 0.4.1__tar.gz

{agent_protocols-0.3.1 → agent_protocols-0.4.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: agent-protocols
-Version: 0.3.1
-Summary: Python SDK for Agent Identity, Agent Profile, and Agent Discourse protocols
+Version: 0.4.1
+Summary: Python SDK for Agent Identity, Agent Profile, Agent Delegation, and Agent Discourse protocols
 Author: LDCLabs
 License: MIT
 Keywords: agent,protocol,ed25519,sdk
@@ -15,14 +15,15 @@ Requires-Dist: requests<3,>=2.31; extra == "http"
 
 # agent-protocols Python SDK
 
-Python SDK for the draft Agent Identity, Agent Profile, and Agent Discourse protocols.
+Python SDK for the draft Agent Identity, Agent Profile, Agent Delegation, and Agent Discourse protocols.
 
 ## Modules
 
 - `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.profile`: `profile.update` payload helpers, delegation discovery hints, validation, materialization.
+- `agent_protocols.delegation`: Agent Delegation principal documents, grant/revoke payloads, credential documents, validation, and materialization.
 - `agent_protocols.discourse`: ADP kernel event constants, the room type system (type definitions, pack imports, type registry, JSON Schema payload validation), join request helpers, room-path checks, kind-based permission and state helpers.
-- `agent_protocols.http_client`: optional requests-based Profile and Discourse clients. Install with `agent-protocols[http]`.
+- `agent_protocols.http_client`: optional requests-based Profile, Delegation, and Discourse clients. Install with `agent-protocols[http]`.
 
 ## Example
 
@@ -42,3 +43,5 @@ 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.
+
+ADP room writes are signed against the current room head. Use `discourse_event` or `type_define_event` with `base_seq` and `base_hash`. Mentions are represented by the event-level `mentions` field, not by `payload.extra`.

{agent_protocols-0.3.1 → agent_protocols-0.4.1}/README.md

@@ -1,13 +1,14 @@
 # agent-protocols Python SDK
 
-Python SDK for the draft Agent Identity, Agent Profile, and Agent Discourse protocols.
+Python SDK for the draft Agent Identity, Agent Profile, Agent Delegation, and Agent Discourse protocols.
 
 ## Modules
 
 - `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.profile`: `profile.update` payload helpers, delegation discovery hints, validation, materialization.
+- `agent_protocols.delegation`: Agent Delegation principal documents, grant/revoke payloads, credential documents, validation, and materialization.
 - `agent_protocols.discourse`: ADP kernel event constants, the room type system (type definitions, pack imports, type registry, JSON Schema payload validation), join request helpers, room-path checks, kind-based permission and state helpers.
-- `agent_protocols.http_client`: optional requests-based Profile and Discourse clients. Install with `agent-protocols[http]`.
+- `agent_protocols.http_client`: optional requests-based Profile, Delegation, and Discourse clients. Install with `agent-protocols[http]`.
 
 ## Example
 
@@ -27,3 +28,5 @@ 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.
+
+ADP room writes are signed against the current room head. Use `discourse_event` or `type_define_event` with `base_seq` and `base_hash`. Mentions are represented by the event-level `mentions` field, not by `payload.extra`.

{agent_protocols-0.3.1 → agent_protocols-0.4.1}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "agent-protocols"
-version = "0.3.1"
-description = "Python SDK for Agent Identity, Agent Profile, and Agent Discourse protocols"
+version = "0.4.1"
+description = "Python SDK for Agent Identity, Agent Profile, Agent Delegation, and Agent Discourse protocols"
 readme = "README.md"
 requires-python = ">=3.10"
 license = { text = "MIT" }

{agent_protocols-0.3.1 → agent_protocols-0.4.1}/src/agent_protocols/__init__.py

@@ -26,12 +26,30 @@ from .identity import (
     verify_request_jwt,
     verify_signature,
     verify_timestamp,
+    with_mention,
+    with_mentions,
+    with_room_head,
     with_room_id,
 )
 from .profile import PROFILE_PROTOCOL, PROFILE_UPDATE, materialize_profile, profile_update_event, validate_profile_update
+from .delegation import (
+    DELEGATION_GRANT,
+    DELEGATION_PROTOCOL,
+    DELEGATION_REVOKE,
+    delegation_grant_event,
+    delegation_revoke_event,
+    materialize_delegation_credential,
+    validate_delegation_envelope,
+    validate_delegation_grant_payload,
+    validate_delegation_revoke_payload,
+    validate_principal_document,
+)
 
 __all__ = [
     "AGENT_ID_PREFIX",
+    "DELEGATION_GRANT",
+    "DELEGATION_PROTOCOL",
+    "DELEGATION_REVOKE",
     "MAX_NONCE_HEADER",
     "PROFILE_PROTOCOL",
     "PROFILE_UPDATE",
@@ -43,10 +61,13 @@ __all__ = [
     "agent_id_from_public_key",
     "canonical_event_bytes",
     "create_event",
+    "delegation_grant_event",
+    "delegation_revoke_event",
     "create_request_jwt_claims",
     "event_hash",
     "event_hash_bytes",
     "materialize_profile",
+    "materialize_delegation_credential",
     "profile_update_event",
     "public_key_bytes",
     "sign_event",
@@ -54,7 +75,11 @@ __all__ = [
     "unix_ms",
     "unix_secs",
     "validate_agent_id",
+    "validate_delegation_envelope",
+    "validate_delegation_grant_payload",
+    "validate_delegation_revoke_payload",
     "validate_nonce",
+    "validate_principal_document",
     "validate_profile_update",
     "verify_envelope",
     "verify_event_hash",
@@ -63,5 +88,8 @@ __all__ = [
     "verify_request_jwt",
     "verify_signature",
     "verify_timestamp",
+    "with_mention",
+    "with_mentions",
+    "with_room_head",
     "with_room_id",
 ]

agent_protocols-0.4.1/src/agent_protocols/delegation.py

@@ -0,0 +1,150 @@
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import urlparse
+
+from .errors import AgentProtocolError
+from .identity import AgentId, Envelope, Event, create_event, validate_agent_id, verify_envelope
+
+DELEGATION_PROTOCOL = "agent-delegation/1.0"
+DELEGATION_GRANT = "delegation.grant"
+DELEGATION_REVOKE = "delegation.revoke"
+
+DelegationGrantPayload = dict[str, Any]
+DelegationRevokePayload = dict[str, Any]
+DelegationCredential = dict[str, Any]
+PrincipalDocument = dict[str, Any]
+
+
+def delegation_grant_event(
+    actor: AgentId,
+    created_at: int,
+    nonce: int,
+    payload: DelegationGrantPayload,
+) -> Event:
+    return create_event(DELEGATION_PROTOCOL, DELEGATION_GRANT, actor, created_at, nonce, payload)
+
+
+def delegation_revoke_event(
+    actor: AgentId,
+    created_at: int,
+    nonce: int,
+    payload: DelegationRevokePayload,
+) -> Event:
+    return create_event(DELEGATION_PROTOCOL, DELEGATION_REVOKE, actor, created_at, nonce, payload)
+
+
+def validate_principal_document(document: PrincipalDocument) -> None:
+    _validate_https_url(document.get("id"), "principal.id")
+    controllers = document.get("controllers")
+    if not isinstance(controllers, list) or not controllers:
+        raise AgentProtocolError(
+            "invalid_principal",
+            "principal document controllers must be non-empty",
+        )
+    for controller in controllers:
+        validate_agent_id(controller)
+    if document.get("delegations_url") is not None:
+        _validate_https_url(document["delegations_url"], "delegations_url")
+
+
+def validate_delegation_grant_payload(
+    payload: DelegationGrantPayload,
+    created_at: int | None = None,
+) -> None:
+    _validate_non_empty(payload.get("id"), "payload.id")
+    _validate_principal_descriptor(payload.get("principal"))
+    validate_agent_id(payload.get("subject"))
+    scopes = payload.get("scopes")
+    if not isinstance(scopes, list) or not scopes:
+        raise AgentProtocolError("invalid_delegation", "delegation scopes must be non-empty")
+    for scope in scopes:
+        _validate_non_empty(scope, "scope")
+    constraints = payload.get("constraints")
+    if constraints is not None and not isinstance(constraints, dict):
+        raise AgentProtocolError("invalid_delegation", "constraints must be an object")
+    expires_at = payload.get("expires_at")
+    if expires_at is not None:
+        not_before = payload.get("not_before", created_at)
+        if not_before is not None and expires_at <= not_before:
+            raise AgentProtocolError(
+                "invalid_delegation",
+                "expires_at must be greater than not_before or created_at",
+            )
+
+
+def validate_delegation_revoke_payload(payload: DelegationRevokePayload) -> None:
+    _validate_non_empty(payload.get("id"), "payload.id")
+    _validate_https_url(payload.get("principal_id"), "principal_id")
+
+
+def validate_delegation_envelope(envelope: Envelope) -> None:
+    verify_envelope(envelope)
+    event = envelope["event"]
+    if event["protocol"] != DELEGATION_PROTOCOL:
+        raise AgentProtocolError(
+            "invalid_event_protocol",
+            f"expected {DELEGATION_PROTOCOL}, got {event['protocol']}",
+        )
+    if event["type"] == DELEGATION_GRANT:
+        validate_delegation_grant_payload(event["payload"], event["created_at"])
+    elif event["type"] == DELEGATION_REVOKE:
+        validate_delegation_revoke_payload(event["payload"])
+    else:
+        raise AgentProtocolError(
+            "invalid_event_type",
+            f"expected {DELEGATION_GRANT} or {DELEGATION_REVOKE}, got {event['type']}",
+        )
+
+
+def materialize_delegation_credential(
+    envelope: Envelope,
+    *,
+    status: str = "active",
+    status_url: str | None = None,
+    updated_at: int | None = None,
+) -> DelegationCredential:
+    validate_delegation_envelope(envelope)
+    event = envelope["event"]
+    if event["type"] != DELEGATION_GRANT:
+        raise AgentProtocolError(
+            "invalid_event_type",
+            "delegation credential materialization requires a grant event",
+        )
+    payload = event["payload"]
+    credential = {
+        "id": payload["id"],
+        "protocol": DELEGATION_PROTOCOL,
+        "principal": payload["principal"],
+        "controller": event["actor"],
+        "subject": payload["subject"],
+        "relationship": payload.get("relationship"),
+        "scopes": payload["scopes"],
+        "constraints": payload.get("constraints"),
+        "not_before": payload.get("not_before"),
+        "expires_at": payload.get("expires_at"),
+        "status": status,
+        "status_url": status_url,
+        "updated_at": updated_at if updated_at is not None else event["created_at"],
+        "event_id": envelope["hash"],
+    }
+    return credential
+
+
+def _validate_principal_descriptor(value: Any) -> None:
+    if not isinstance(value, dict):
+        raise AgentProtocolError("invalid_principal", "principal must be an object")
+    _validate_https_url(value.get("id"), "principal.id")
+
+
+def _validate_https_url(value: Any, field: str) -> None:
+    if not isinstance(value, str):
+        raise AgentProtocolError("invalid_url", f"{field} must be an HTTPS URL")
+    parsed = urlparse(value)
+    if parsed.scheme != "https" or not parsed.netloc:
+        raise AgentProtocolError("invalid_url", f"{field} must be an HTTPS URL")
+
+
+def _validate_non_empty(value: Any, field: str) -> None:
+    if not isinstance(value, str) or not value.strip():
+        raise AgentProtocolError("invalid_delegation", f"{field} must not be empty")

{agent_protocols-0.3.1 → agent_protocols-0.4.1}/src/agent_protocols/discourse.py

@@ -18,7 +18,17 @@ import rfc8785
 from jsonschema.validators import Draft202012Validator
 
 from .errors import AgentProtocolError
-from .identity import AgentId, Envelope, Event, create_event, verify_envelope, with_room_id
+from .identity import (
+    AgentId,
+    Envelope,
+    Event,
+    MAX_SAFE_NONCE,
+    create_event,
+    validate_agent_id,
+    verify_envelope,
+    with_room_head,
+    with_room_id,
+)
 
 DISCOURSE_PROTOCOL = "agent-discourse/1.0"
 
@@ -68,6 +78,8 @@ Role = Literal["moderator", "speaker", "observer"]
 TypeKind = Literal["message", "signal", "control"]
 TypeStatus = Literal["active", "deprecated", "disabled"]
 JoinRequestStatus = Literal["pending", "approved", "rejected", "expired"]
+JoinDecision = Literal["approve", "reject"]
+Visibility = Literal["public", "restricted", "private"]
 
 ROLES = ("moderator", "speaker", "observer")
 TYPE_KINDS = ("message", "signal", "control")
@@ -82,24 +94,73 @@ class PermissionContext(TypedDict, total=False):
 
     role: Role
     is_creator: bool
+    public_join_allowed: bool
     join_request_approved: bool
 
 
+class AgentStatusInput(TypedDict, total=False):
+    state: str
+    summary: str
+    seen_seq: int
+    seen_hash: str
+    claim_id: str
+    activity: str
+    expires_at: int
+    extra: dict[str, Any]
+
+
+class AgentStatus(TypedDict, total=False):
+    room_id: str
+    agent_id: AgentId
+    state: str
+    summary: str
+    seen_seq: int
+    seen_hash: str
+    claim_id: str
+    activity: str
+    expires_at: int
+    updated_at: int
+    extra: dict[str, Any]
+
+
 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 type_define_event(
-    actor: AgentId, created_at: int, nonce: int, room_id: str, declaration: dict[str, Any]
+    actor: AgentId,
+    created_at: int,
+    nonce: int,
+    room_id: str,
+    base_seq: int,
+    base_hash: str,
+    declaration: dict[str, Any],
 ) -> Event:
-    return with_room_id(
-        create_event(DISCOURSE_PROTOCOL, TYPE_DEFINE, actor, created_at, nonce, declaration),
-        room_id,
+    return with_room_head(
+        with_room_id(
+            create_event(DISCOURSE_PROTOCOL, TYPE_DEFINE, actor, created_at, nonce, declaration),
+            room_id,
+        ),
+        base_seq,
+        base_hash,
     )
 
 
-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 discourse_event(
+    event_type: str,
+    actor: AgentId,
+    created_at: int,
+    nonce: int,
+    room_id: str,
+    base_seq: int,
+    base_hash: str,
+    payload: Any,
+) -> Event:
+    return with_room_head(
+        with_room_id(create_event(DISCOURSE_PROTOCOL, event_type, actor, created_at, nonce, payload), room_id),
+        base_seq,
+        base_hash,
+    )
 
 
 def is_builtin_event_type(event_type: str) -> bool:
@@ -117,25 +178,54 @@ def validate_discourse_envelope(envelope: Envelope) -> None:
     if protocol != DISCOURSE_PROTOCOL:
         raise AgentProtocolError("invalid_event_protocol", f"expected {DISCOURSE_PROTOCOL}, got {protocol}")
     if event["type"] == ROOM_CREATE:
-        if "room_id" in event:
-            raise AgentProtocolError("invalid_event", "room.create must not include room_id")
-    elif "room_id" not in event:
-        raise AgentProtocolError("missing_room_id", "event requires a room_id")
+        _validate_room_create_event_fields(event)
+    else:
+        if "room_id" not in event:
+            raise AgentProtocolError("missing_room_id", "event requires a room_id")
+        validate_room_head_precondition(event)
+        _validate_mentions(event.get("mentions"))
 
 
 def validate_room_path(envelope: Envelope, path_room_id: str) -> None:
     event = envelope["event"]
     actual = event.get("room_id")
     if event["type"] == ROOM_CREATE:
-        if actual is not None:
-            raise AgentProtocolError("invalid_event", "room.create must not include room_id")
+        _validate_room_create_event_fields(event)
         return
+    validate_room_head_precondition(event)
+    _validate_mentions(event.get("mentions"))
     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 _validate_room_create_event_fields(event: Event) -> None:
+    if any(field in event for field in ("room_id", "base_seq", "base_hash", "mentions")):
+        raise AgentProtocolError(
+            "invalid_event",
+            "room.create must not include room_id, base_seq, base_hash, or mentions",
+        )
+
+
+def validate_room_head_precondition(event: Event) -> None:
+    base_seq = event.get("base_seq")
+    base_hash = event.get("base_hash")
+    if not isinstance(base_seq, int) or base_seq < 1 or base_seq > MAX_SAFE_NONCE:
+        raise AgentProtocolError("invalid_event", "base_seq must be a positive safe JSON integer")
+    if not isinstance(base_hash, str) or not base_hash.strip():
+        raise AgentProtocolError("invalid_event", "base_hash must not be empty")
+
+
+def _validate_mentions(mentions: Any) -> None:
+    if mentions is None:
+        return
+    if not isinstance(mentions, list):
+        raise AgentProtocolError("invalid_event", "mentions must be an Agent ID array")
+    for mention in mentions:
+        validate_agent_id(mention)
+
+
 def validate_custom_event_type_name(name: str) -> None:
     """Checks the shape of a custom event type name: lowercase dot-separated,
     at least two segments, not built-in, not under a reserved prefix."""
@@ -349,6 +439,19 @@ def validate_message_create_payload(payload: dict[str, Any]) -> None:
         raise AgentProtocolError("invalid_event", "content_type must not be empty")
 
 
+def validate_room_join_payload(payload: dict[str, Any]) -> None:
+    if payload.get("role") not in ROLES:
+        raise AgentProtocolError("invalid_event", f"invalid room role: {payload.get('role')}")
+    request_id = payload.get("request_id")
+    if request_id is not None and not str(request_id).strip():
+        raise AgentProtocolError("invalid_event", "request_id must not be empty")
+    if request_id is not None and "perspective" in payload:
+        raise AgentProtocolError(
+            "invalid_event",
+            "room.join payload cannot include both request_id and perspective",
+        )
+
+
 def server_record_hash_payload(
     room_id: str,
     seq: int,
@@ -448,7 +551,7 @@ def can_submit_event(
     if event_type == ROOM_CREATE:
         return True
     if event_type == ROOM_JOIN:
-        return bool(context.get("join_request_approved"))
+        return bool(context.get("public_join_allowed") or context.get("join_request_approved"))
     if event_type == ROOM_LEAVE:
         return is_creator or role is not None
     if event_type in {ROOM_JOIN_REVIEW, ROOM_MEMBER_ROLE_UPDATE, ROOM_CLOSE, ROOM_CANCEL, TYPE_DEFINE}:

{agent_protocols-0.3.1 → agent_protocols-0.4.1}/src/agent_protocols/http_client.py

@@ -53,6 +53,43 @@ class DiscourseClient:
     def room(self, room_id: str) -> dict[str, Any]:
         return self._get(f"/v1/rooms/{room_id}")
 
+    def public_rooms(
+        self,
+        *,
+        status: str | None = None,
+        tag: str | None = None,
+        keyword: str | None = None,
+        creator: str | None = None,
+        starts_after: int | None = None,
+        ends_before: int | None = None,
+        language: str | None = None,
+        limit: int | None = None,
+        cursor: str | None = None,
+    ) -> list[dict[str, Any]]:
+        query = urlencode(
+            {
+                key: value
+                for key, value in {
+                    "status": status,
+                    "tag": tag,
+                    "keyword": keyword,
+                    "creator": creator,
+                    "starts_after": starts_after,
+                    "ends_before": ends_before,
+                    "language": language,
+                    "limit": limit,
+                    "cursor": cursor,
+                }.items()
+                if value is not None
+            },
+            quote_via=quote,
+        )
+        suffix = f"?{query}" if query else ""
+        return self._get(f"/v1/rooms/public{suffix}")
+
+    def my_rooms(self, jwt: str) -> list[dict[str, Any]]:
+        return self._get("/v1/me/rooms", jwt=jwt)
+
     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)
 
@@ -95,8 +132,17 @@ class DiscourseClient:
         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 agent_statuses(self, room_id: str, jwt: str | None = None) -> dict[str, Any]:
+        return self._get(f"/v1/rooms/{room_id}/agent-status", jwt=jwt)
+
+    def agent_status(self, room_id: str, agent_id: AgentId, jwt: str | None = None) -> dict[str, Any]:
+        return self._get(f"/v1/rooms/{room_id}/agent-status/{agent_id}", jwt=jwt)
+
+    def set_agent_status(self, room_id: str, jwt: str, status: dict[str, Any]) -> dict[str, Any]:
+        return self._put(f"/v1/rooms/{room_id}/agent-status", status, jwt=jwt)
+
+    def sse_events_url(self, room_id: str) -> str:
+        return sse_events_url(self.base_url, room_id)
 
     def archive(self, room_id: str) -> dict[str, Any]:
         return self._get(f"/v1/rooms/{room_id}/archive")
@@ -111,14 +157,56 @@ class DiscourseClient:
         response.raise_for_status()
         return response.json()
 
+    def _put(self, path: str, body: Any, jwt: str | None = None) -> Any:
+        response = self.session.put(self.base_url + path, json=body, headers=_auth_headers(jwt))
+        response.raise_for_status()
+        return response.json()
+
+
+class DelegationClient:
+    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-delegation")
+
+    def principal(self, principal_url: str | None = None) -> dict[str, Any]:
+        response = self.session.get(
+            principal_url or self.base_url,
+            headers={"Accept": "application/json"},
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def delegation(self, delegation_id: str) -> dict[str, Any]:
+        return self._get(f"/v1/delegations/{delegation_id}")
+
+    def delegation_status(self, delegation_id: str) -> dict[str, Any]:
+        return self._get(f"/v1/delegations/{delegation_id}/status")
+
+    def delegation_events(self, delegation_id: str) -> dict[str, Any]:
+        return self._get(f"/v1/delegations/{delegation_id}/events")
+
+    def submit_delegation_event(self, envelope: Envelope) -> dict[str, Any]:
+        return self._post("/v1/delegations", envelope)
+
+    def query_delegations(self, request: dict[str, Any]) -> dict[str, Any]:
+        return self._post("/v1/delegations/query", request)
+
+    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()
+
 
-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 sse_events_url(base_url: str, room_id: str) -> str:
+    return f"{base_url.rstrip('/')}/v1/rooms/{quote(room_id, safe='')}/events/live"
 
 
 def _auth_headers(jwt: str | None) -> dict[str, str] | None:

{agent_protocols-0.3.1 → agent_protocols-0.4.1}/src/agent_protocols/identity.py

@@ -171,6 +171,31 @@ def with_room_id(event: Event, room_id: str) -> Event:
     return next_event
 
 
+def with_room_head(event: Event, base_seq: int, base_hash: str) -> Event:
+    validate_nonce(base_seq)
+    if not isinstance(base_hash, str) or not base_hash.strip():
+        raise AgentProtocolError("invalid_event", "base_hash must not be empty")
+    next_event = dict(event)
+    next_event["base_seq"] = base_seq
+    next_event["base_hash"] = base_hash
+    return next_event
+
+
+def with_mentions(event: Event, mentions: list[AgentId]) -> Event:
+    for mention in mentions:
+        validate_agent_id(mention)
+    next_event = dict(event)
+    next_event["mentions"] = list(mentions)
+    return next_event
+
+
+def with_mention(event: Event, agent_id: AgentId) -> Event:
+    validate_agent_id(agent_id)
+    next_event = dict(event)
+    next_event["mentions"] = [*next_event.get("mentions", []), agent_id]
+    return next_event
+
+
 def canonical_event_bytes(event: Event) -> bytes:
     canonical = rfc8785.dumps(event)
     return canonical if isinstance(canonical, bytes) else canonical.encode()

{agent_protocols-0.3.1 → agent_protocols-0.4.1}/src/agent_protocols/profile.py

@@ -42,6 +42,7 @@ def materialize_profile(envelope: Envelope) -> AgentProfile:
         "capabilities": payload.get("capabilities", []),
         "service_endpoints": payload.get("service_endpoints", []),
         "links": payload.get("links", []),
+        "delegations": payload.get("delegations", []),
         "extra": payload.get("extra", {}),
         "updated_at": envelope["event"]["created_at"],
         "event_id": envelope["hash"],

{agent_protocols-0.3.1 → agent_protocols-0.4.1}/src/agent_protocols.egg-info/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: agent-protocols
-Version: 0.3.1
-Summary: Python SDK for Agent Identity, Agent Profile, and Agent Discourse protocols
+Version: 0.4.1
+Summary: Python SDK for Agent Identity, Agent Profile, Agent Delegation, and Agent Discourse protocols
 Author: LDCLabs
 License: MIT
 Keywords: agent,protocol,ed25519,sdk
@@ -15,14 +15,15 @@ Requires-Dist: requests<3,>=2.31; extra == "http"
 
 # agent-protocols Python SDK
 
-Python SDK for the draft Agent Identity, Agent Profile, and Agent Discourse protocols.
+Python SDK for the draft Agent Identity, Agent Profile, Agent Delegation, and Agent Discourse protocols.
 
 ## Modules
 
 - `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.profile`: `profile.update` payload helpers, delegation discovery hints, validation, materialization.
+- `agent_protocols.delegation`: Agent Delegation principal documents, grant/revoke payloads, credential documents, validation, and materialization.
 - `agent_protocols.discourse`: ADP kernel event constants, the room type system (type definitions, pack imports, type registry, JSON Schema payload validation), join request helpers, room-path checks, kind-based permission and state helpers.
-- `agent_protocols.http_client`: optional requests-based Profile and Discourse clients. Install with `agent-protocols[http]`.
+- `agent_protocols.http_client`: optional requests-based Profile, Delegation, and Discourse clients. Install with `agent-protocols[http]`.
 
 ## Example
 
@@ -42,3 +43,5 @@ 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.
+
+ADP room writes are signed against the current room head. Use `discourse_event` or `type_define_event` with `base_seq` and `base_hash`. Mentions are represented by the event-level `mentions` field, not by `payload.extra`.

{agent_protocols-0.3.1 → agent_protocols-0.4.1}/src/agent_protocols.egg-info/SOURCES.txt

@@ -1,6 +1,7 @@
 README.md
 pyproject.toml
 src/agent_protocols/__init__.py
+src/agent_protocols/delegation.py
 src/agent_protocols/discourse.py
 src/agent_protocols/errors.py
 src/agent_protocols/http_client.py
@@ -11,6 +12,7 @@ src/agent_protocols.egg-info/SOURCES.txt
 src/agent_protocols.egg-info/dependency_links.txt
 src/agent_protocols.egg-info/requires.txt
 src/agent_protocols.egg-info/top_level.txt
+tests/test_delegation.py
 tests/test_discourse.py
 tests/test_discourse_coverage.py
 tests/test_http_client.py

agent_protocols-0.4.1/tests/test_delegation.py

@@ -0,0 +1,124 @@
+import unittest
+
+from agent_protocols.delegation import (
+    DELEGATION_GRANT,
+    DELEGATION_PROTOCOL,
+    DELEGATION_REVOKE,
+    delegation_grant_event,
+    delegation_revoke_event,
+    materialize_delegation_credential,
+    validate_delegation_envelope,
+    validate_delegation_grant_payload,
+    validate_principal_document,
+)
+from agent_protocols.identity import AgentSigner, create_event
+
+
+class DelegationTests(unittest.TestCase):
+    def test_grant_event_materializes_credential(self):
+        controller = AgentSigner.from_seed(bytes([31]) * 32)
+        subject = AgentSigner.from_seed(bytes([32]) * 32)
+        payload = {
+            "id": "del_01J8ZM7A3G2T9B4Q6X8R0N1P2Q",
+            "principal": {
+                "id": "https://al.ink/yan",
+                "type": "person",
+                "name": "Yan",
+            },
+            "subject": subject.agent_id(),
+            "relationship": "primary_delegate",
+            "scopes": ["inbox.screen", "meeting.propose"],
+            "constraints": {"requires_human_approval": ["meeting.accept"]},
+            "not_before": 1_779_753_600_000,
+            "expires_at": 1_790_000_000_000,
+        }
+        envelope = controller.sign_event(
+            delegation_grant_event(controller.agent_id(), 1_779_753_600_000, 1, payload)
+        )
+
+        validate_delegation_envelope(envelope)
+        credential = materialize_delegation_credential(
+            envelope,
+            status_url="https://al.ink/v1/delegations/del/status",
+        )
+
+        self.assertEqual(envelope["event"]["type"], DELEGATION_GRANT)
+        self.assertEqual(credential["protocol"], DELEGATION_PROTOCOL)
+        self.assertEqual(credential["controller"], controller.agent_id())
+        self.assertEqual(credential["subject"], subject.agent_id())
+        self.assertEqual(credential["status"], "active")
+        self.assertEqual(credential["event_id"], envelope["hash"])
+
+    def test_revoke_event_and_invalid_payloads(self):
+        controller = AgentSigner.from_seed(bytes([33]) * 32)
+        envelope = controller.sign_event(
+            delegation_revoke_event(
+                controller.agent_id(),
+                1_779_753_700_000,
+                2,
+                {
+                    "id": "del_01J8ZM7A3G2T9B4Q6X8R0N1P2Q",
+                    "principal_id": "https://al.ink/yan",
+                    "reason": "rotated_primary_agent",
+                },
+            )
+        )
+
+        self.assertEqual(envelope["event"]["type"], DELEGATION_REVOKE)
+        validate_delegation_envelope(envelope)
+        with self.assertRaisesRegex(Exception, "HTTPS|scopes"):
+            validate_delegation_grant_payload(
+                {
+                    "id": "del",
+                    "principal": {"id": "http://example.com"},
+                    "subject": controller.agent_id(),
+                    "scopes": [],
+                }
+            )
+
+    def test_principal_document_and_event_type_validation(self):
+        controller = AgentSigner.from_seed(bytes([34]) * 32)
+        validate_principal_document(
+            {
+                "id": "https://profiles.example.com/org/acme",
+                "controllers": [controller.agent_id()],
+                "delegations_url": "https://profiles.example.com/v1/delegations/query",
+            }
+        )
+        with self.assertRaises(Exception):
+            validate_principal_document(
+                {
+                    "id": "https://profiles.example.com/org/acme",
+                    "controllers": [],
+                }
+            )
+
+        wrong = controller.sign_event(
+            create_event(
+                DELEGATION_PROTOCOL,
+                "delegation.unknown",
+                controller.agent_id(),
+                1,
+                1,
+                {"id": "del"},
+            )
+        )
+        with self.assertRaisesRegex(Exception, "delegation.grant"):
+            validate_delegation_envelope(wrong)
+
+    def test_rejects_malformed_https_like_principal_urls(self):
+        signer = AgentSigner.from_seed(bytes([35]) * 32)
+        for principal_id in ("https://", "https://[::1", "http://example.com"):
+            with self.assertRaises(Exception):
+                validate_delegation_grant_payload(
+                    {
+                        "id": "del",
+                        "principal": {"id": principal_id},
+                        "subject": signer.agent_id(),
+                        "scopes": ["scope"],
+                    }
+                )
+
+
+if __name__ == "__main__":
+    unittest.main()

{agent_protocols-0.3.1 → agent_protocols-0.4.1}/tests/test_discourse.py

@@ -42,7 +42,7 @@ from agent_protocols.discourse import (
     verify_server_record_chain,
 )
 from agent_protocols.errors import AgentProtocolError
-from agent_protocols.http_client import websocket_events_url
+from agent_protocols.http_client import sse_events_url
 from agent_protocols.identity import AgentSigner, create_event
 
 PACKS_PATH = Path(__file__).resolve().parents[3] / "docs/protocols/agent-discourse/1.0.packs.json"
@@ -143,6 +143,8 @@ class DiscourseTests(unittest.TestCase):
             },
         )
         event["room_id"] = "d8ftedhpqhsusbg001tg"
+        event["base_seq"] = 17
+        event["base_hash"] = "GDt8oHZQfQ3jl5ZUfyNxKZu07yAJdDYuaw_jf_JjLYs"
         envelope = moderator.sign_event(event)
         validator = Draft202012Validator(json.loads(SCHEMA_PATH.read_text()))
 
@@ -336,7 +338,15 @@ class DiscourseTests(unittest.TestCase):
 
     def test_signs_and_validates_type_define_envelopes(self):
         signer = AgentSigner.from_seed(bytes([16]) * 32)
-        event = type_define_event(signer.agent_id(), 100, 1, "d8ftedhpqhsusbg001tg", dict(FINDING_DEF))
+        event = type_define_event(
+            signer.agent_id(),
+            100,
+            1,
+            "d8ftedhpqhsusbg001tg",
+            1,
+            "room-create-head",
+            dict(FINDING_DEF),
+        )
         envelope = signer.sign_event(event)
         validate_discourse_envelope(envelope)
 
@@ -371,6 +381,8 @@ class DiscourseTests(unittest.TestCase):
             {"content_type": "text/plain", "content": "hello"},
         )
         event2["room_id"] = "room123"
+        event2["base_seq"] = 1
+        event2["base_hash"] = record1["hash"]
         envelope2 = signer.sign_event(event2)
         record2 = build_server_record("room123", 2, record1["hash"], 130, envelope2)
 
@@ -383,10 +395,10 @@ class DiscourseTests(unittest.TestCase):
         with self.assertRaises(AgentProtocolError):
             verify_server_record_chain([{**record2, "pre_hash": "bad"}])
 
-    def test_builds_websocket_event_stream_url(self):
+    def test_builds_sse_event_stream_url(self):
         self.assertEqual(
-            websocket_events_url("https://api.example.com", "room123", "jwt.token"),
-            "wss://api.example.com/v1/rooms/room123/events/live?access_token=jwt.token",
+            sse_events_url("https://api.example.com", "room123"),
+            "https://api.example.com/v1/rooms/room123/events/live",
         )
 
 

{agent_protocols-0.3.1 → agent_protocols-0.4.1}/tests/test_discourse_coverage.py

@@ -40,13 +40,15 @@ class HelperBranchTests(unittest.TestCase):
         signer = AgentSigner.from_seed(bytes([60]) * 32)
         self.assertTrue(event_requires_room_id(MESSAGE_CREATE))
         self.assertFalse(event_requires_room_id(ROOM_CREATE))
-        event = discourse_event(MESSAGE_CREATE, signer.agent_id(), 1, 1, "room1", {"a": 1})
+        event = discourse_event(MESSAGE_CREATE, signer.agent_id(), 1, 1, "room1", 1, "room-create-head", {"a": 1})
         self.assertEqual(event["room_id"], "room1")
+        self.assertEqual(event["base_seq"], 1)
+        self.assertEqual(event["base_hash"], "room-create-head")
         self.assertEqual(event["protocol"], DISCOURSE_PROTOCOL)
 
     def test_validate_discourse_envelope_rejects_foreign_protocol(self):
         signer = AgentSigner.from_seed(bytes([61]) * 32)
-        event = discourse_event(MESSAGE_CREATE, signer.agent_id(), 1, 1, "room1", {"a": 1})
+        event = discourse_event(MESSAGE_CREATE, signer.agent_id(), 1, 1, "room1", 1, "room-create-head", {"a": 1})
         event["protocol"] = "other/1.0"
         envelope = signer.sign_event(event)
         with self.assertRaises(AgentProtocolError):
@@ -55,7 +57,7 @@ class HelperBranchTests(unittest.TestCase):
     def test_validate_room_path_matches_mismatches_and_requires_room_id(self):
         signer = AgentSigner.from_seed(bytes([62]) * 32)
         in_room = signer.sign_event(
-            discourse_event(MESSAGE_CREATE, signer.agent_id(), 1, 1, "room1", {"a": 1})
+            discourse_event(MESSAGE_CREATE, signer.agent_id(), 1, 1, "room1", 1, "room-create-head", {"a": 1})
         )
         validate_room_path(in_room, "room1")
         with self.assertRaises(AgentProtocolError):
@@ -63,7 +65,7 @@ class HelperBranchTests(unittest.TestCase):
 
         no_room = {
             "hash": "h",
-            "event": {"type": MESSAGE_CREATE, "protocol": DISCOURSE_PROTOCOL},
+            "event": {"type": MESSAGE_CREATE, "protocol": DISCOURSE_PROTOCOL, "base_seq": 1, "base_hash": "room-create-head"},
             "signature": "s",
         }
         with self.assertRaises(AgentProtocolError):
@@ -169,7 +171,16 @@ class ServerRecordChainTests(unittest.TestCase):
 
         def make(seq, nonce, pre_hash):
             envelope = signer.sign_event(
-                discourse_event(MESSAGE_CREATE, signer.agent_id(), 100, nonce, "room1", {"a": 1})
+                discourse_event(
+                    MESSAGE_CREATE,
+                    signer.agent_id(),
+                    100,
+                    nonce,
+                    "room1",
+                    1 if seq == 1 else seq - 1,
+                    pre_hash or "room-create-head",
+                    {"a": 1},
+                )
             )
             return build_server_record("room1", seq, pre_hash, 100 + seq, envelope)
 

{agent_protocols-0.3.1 → agent_protocols-0.4.1}/tests/test_http_client.py

@@ -2,9 +2,10 @@ import unittest
 
 import agent_protocols.http_client as http_client
 from agent_protocols.http_client import (
+    DelegationClient,
     DiscourseClient,
     ProfileClient,
-    websocket_events_url,
+    sse_events_url,
 )
 from agent_protocols.identity import AgentSigner
 
@@ -37,6 +38,10 @@ class FakeSession:
         self.calls.append(("POST", url, headers, json))
         return self._responses.pop(0)
 
+    def put(self, url, json=None, headers=None):
+        self.calls.append(("PUT", url, headers, json))
+        return self._responses.pop(0)
+
 
 class ProfileClientTests(unittest.TestCase):
     def test_every_endpoint_uses_the_expected_method_and_path(self):
@@ -119,28 +124,96 @@ class DiscourseClientTests(unittest.TestCase):
         self.assertEqual(session.calls[10][2], {"Authorization": "Bearer jwt-d"})
         self.assertEqual(urls[11], "https://api.example.com/v1/rooms/room1/archive")
 
-    def test_websocket_events_url_method(self):
+    def test_sse_events_url_method(self):
         session = FakeSession([])
         client = DiscourseClient("https://api.example.com", session=session)
         self.assertEqual(
-            client.websocket_events_url("room1", "jwt.token"),
-            websocket_events_url("https://api.example.com", "room1", "jwt.token"),
+            client.sse_events_url("room1"),
+            sse_events_url("https://api.example.com", "room1"),
+        )
+
+    def test_public_rooms_my_rooms_and_agent_status_endpoints(self):
+        session = FakeSession([FakeResponse({"ok": True}) for _ in range(5)])
+        client = DiscourseClient("https://api.example.com/", session=session)
+
+        client.public_rooms(
+            status="active",
+            tag="code review",
+            starts_after=10,
+            ends_before=20,
+            limit=5,
+            cursor="next page",
+        )
+        client.my_rooms("jwt-me")
+        client.agent_statuses("room1", jwt="jwt-statuses")
+        client.agent_status("room1", AGENT_ID, jwt="jwt-status")
+        client.set_agent_status("room1", "jwt-set", {"state": "idle", "expires_at": 2})
+
+        urls = [call[1] for call in session.calls]
+        self.assertEqual(
+            urls[0],
+            "https://api.example.com/v1/rooms/public?status=active&tag=code%20review&starts_after=10&ends_before=20&limit=5&cursor=next%20page",
         )
+        self.assertEqual(urls[1], "https://api.example.com/v1/me/rooms")
+        self.assertEqual(session.calls[1][2], {"Authorization": "Bearer jwt-me"})
+        self.assertEqual(urls[2], "https://api.example.com/v1/rooms/room1/agent-status")
+        self.assertEqual(session.calls[2][2], {"Authorization": "Bearer jwt-statuses"})
+        self.assertEqual(urls[3], f"https://api.example.com/v1/rooms/room1/agent-status/{AGENT_ID}")
+        self.assertEqual(session.calls[4][0], "PUT")
+        self.assertEqual(session.calls[4][2], {"Authorization": "Bearer jwt-set"})
+        self.assertEqual(session.calls[4][3], {"state": "idle", "expires_at": 2})
+
+
+class DelegationClientTests(unittest.TestCase):
+    def test_every_endpoint_uses_expected_method_and_path(self):
+        session = FakeSession([FakeResponse({"ok": True}) for _ in range(7)])
+        client = DelegationClient("https://al.ink/", session=session)
+        envelope = {
+            "hash": "h",
+            "event": {
+                "protocol": "agent-delegation/1.0",
+                "type": "delegation.revoke",
+                "actor": AGENT_ID,
+                "created_at": 1,
+                "nonce": 1,
+                "payload": {"id": "del_1", "principal_id": "https://al.ink/yan"},
+            },
+            "signature": "s",
+        }
+
+        client.protocol()
+        client.principal("https://al.ink/yan")
+        client.delegation("del_1")
+        client.delegation_status("del_1")
+        client.delegation_events("del_1")
+        client.submit_delegation_event(envelope)
+        client.query_delegations({"subject": AGENT_ID, "status": "active", "limit": 20})
+
+        urls = [call[1] for call in session.calls]
+        self.assertEqual(urls[0], "https://al.ink/.well-known/agent-delegation")
+        self.assertEqual(urls[1], "https://al.ink/yan")
+        self.assertEqual(session.calls[1][2], {"Accept": "application/json"})
+        self.assertEqual(urls[2], "https://al.ink/v1/delegations/del_1")
+        self.assertEqual(urls[3], "https://al.ink/v1/delegations/del_1/status")
+        self.assertEqual(urls[4], "https://al.ink/v1/delegations/del_1/events")
+        self.assertEqual((session.calls[5][0], urls[5]), ("POST", "https://al.ink/v1/delegations"))
+        self.assertEqual((session.calls[6][0], urls[6]), ("POST", "https://al.ink/v1/delegations/query"))
+        self.assertEqual(session.calls[6][3]["status"], "active")
 
 
 class HelperTests(unittest.TestCase):
-    def test_websocket_events_url_rewrites_schemes(self):
+    def test_sse_events_url_preserves_http_schemes(self):
         self.assertEqual(
-            websocket_events_url("https://api.example.com", "room123", "jwt.token"),
-            "wss://api.example.com/v1/rooms/room123/events/live?access_token=jwt.token",
+            sse_events_url("https://api.example.com", "room123"),
+            "https://api.example.com/v1/rooms/room123/events/live",
         )
         self.assertEqual(
-            websocket_events_url("http://api.example.com/", "room 1", "a+b"),
-            "ws://api.example.com/v1/rooms/room%201/events/live?access_token=a%2Bb",
+            sse_events_url("http://api.example.com/", "room 1"),
+            "http://api.example.com/v1/rooms/room%201/events/live",
         )
         self.assertEqual(
-            websocket_events_url("ftp://api.example.com", "r", "t"),
-            "ftp://api.example.com/v1/rooms/r/events/live?access_token=t",
+            sse_events_url("ftp://api.example.com", "r"),
+            "ftp://api.example.com/v1/rooms/r/events/live",
         )
 
     def test_requests_session_factory(self):

{agent_protocols-0.3.1 → agent_protocols-0.4.1}/tests/test_identity_coverage.py

@@ -21,9 +21,12 @@ from agent_protocols.identity import (
     unix_ms,
     unix_secs,
     validate_agent_id,
+    verify_envelope,
     verify_event_hash_signature,
     verify_request_jwt,
     verify_timestamp,
+    with_mention,
+    with_room_head,
     with_room_id,
 )
 from agent_protocols.errors import AgentProtocolError
@@ -65,8 +68,18 @@ class AgentIdTests(unittest.TestCase):
 class EventTests(unittest.TestCase):
     def test_create_event_and_with_room_id(self):
         signer = AgentSigner.from_seed(bytes([21]) * 32)
+        target = AgentSigner.from_seed(bytes([22]) * 32)
         event = create_event("p", "t", signer.agent_id(), 1000, 1, {"a": 1})
         self.assertEqual(with_room_id(event, "room1")["room_id"], "room1")
+        room_event = with_mention(with_room_head(with_room_id(event, "room1"), 1, "room-create-head"), target.agent_id())
+        self.assertEqual(room_event["base_seq"], 1)
+        self.assertEqual(room_event["base_hash"], "room-create-head")
+        self.assertEqual(room_event["mentions"], [target.agent_id()])
+        verify_envelope(signer.sign_event(room_event))
+        with self.assertRaises(AgentProtocolError):
+            with_room_head(event, 0, "head")
+        with self.assertRaises(AgentProtocolError):
+            with_mention(event, "bad-agent")
         with self.assertRaises(AgentProtocolError):
             create_event("p", "t", "bad-actor", 1, 1, {})
 

{agent_protocols-0.3.1 → agent_protocols-0.4.1}/tests/test_profile.py

@@ -13,6 +13,14 @@ class ProfileTests(unittest.TestCase):
             "capabilities": ["research"],
             "extra": {"domain": "research"},
             "links": [{"name": "Homepage", "url": "https://example.com", "rel": "homepage"}],
+            "delegations": [
+                {
+                    "principal": {"id": "https://al.ink/yan", "type": "person", "name": "Yan"},
+                    "relationship": "primary_delegate",
+                    "scopes": ["inbox.screen"],
+                    "credential_url": "https://al.ink/v1/delegations/del_1",
+                }
+            ],
         }
         envelope = signer.sign_event(profile_update_event(signer.agent_id(), 1_779_753_600_000, 1, payload))
 
@@ -22,6 +30,7 @@ class ProfileTests(unittest.TestCase):
         self.assertEqual(profile["name"], "ResearchAgent-v3")
         self.assertIsNone(profile["username"])
         self.assertEqual(profile["links"], payload["links"])
+        self.assertEqual(profile["delegations"], payload["delegations"])
         self.assertEqual(profile["extra"], payload["extra"])
         self.assertEqual(profile["updated_at"], 1_779_753_600_000)
         self.assertEqual(profile["event_id"], envelope["hash"])