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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-protocols
-Version: 0.4.1
+Version: 0.5.0
 Summary: Python SDK for Agent Identity, Agent Profile, Agent Delegation, and Agent Discourse protocols
 Author: LDCLabs
 License: MIT
@@ -42,6 +42,6 @@ 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 Profile has no `username` field: the Agent ID is the identity key, and the latest profile is the accepted `profile.update` with the greatest `nonce`.
 
-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`.
+ADP room writes declare a signed `base_seq` / `base_hash`: discussion and contract writes must match the current room head, while `signal`-kind writes — including the built-in membership events — only anchor to an accepted record and never contend for the 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.4.1 → agent_protocols-0.5.0}/README.md

@@ -27,6 +27,6 @@ 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 Profile has no `username` field: the Agent ID is the identity key, and the latest profile is the accepted `profile.update` with the greatest `nonce`.
 
-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`.
+ADP room writes declare a signed `base_seq` / `base_hash`: discussion and contract writes must match the current room head, while `signal`-kind writes — including the built-in membership events — only anchor to an accepted record and never contend for the 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.4.1 → agent_protocols-0.5.0}/pyproject.toml

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

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

@@ -13,6 +13,7 @@ from .identity import (
     event_hash,
     event_hash_bytes,
     public_key_bytes,
+    service_origin,
     sign_event,
     sign_event_hash,
     unix_ms,
@@ -31,7 +32,14 @@ from .identity import (
     with_room_head,
     with_room_id,
 )
-from .profile import PROFILE_PROTOCOL, PROFILE_UPDATE, materialize_profile, profile_update_event, validate_profile_update
+from .profile import (
+    PROFILE_PROTOCOL,
+    PROFILE_UPDATE,
+    latest_profile_update,
+    materialize_profile,
+    profile_update_event,
+    validate_profile_update,
+)
 from .delegation import (
     DELEGATION_GRANT,
     DELEGATION_PROTOCOL,
@@ -41,6 +49,7 @@ from .delegation import (
     materialize_delegation_credential,
     validate_delegation_envelope,
     validate_delegation_grant_payload,
+    validate_delegation_query_request,
     validate_delegation_revoke_payload,
     validate_principal_document,
 )
@@ -66,10 +75,12 @@ __all__ = [
     "create_request_jwt_claims",
     "event_hash",
     "event_hash_bytes",
+    "latest_profile_update",
     "materialize_profile",
     "materialize_delegation_credential",
     "profile_update_event",
     "public_key_bytes",
+    "service_origin",
     "sign_event",
     "sign_event_hash",
     "unix_ms",
@@ -77,6 +88,7 @@ __all__ = [
     "validate_agent_id",
     "validate_delegation_envelope",
     "validate_delegation_grant_payload",
+    "validate_delegation_query_request",
     "validate_delegation_revoke_payload",
     "validate_nonce",
     "validate_principal_document",

{agent_protocols-0.4.1 → agent_protocols-0.5.0}/src/agent_protocols/delegation.py

@@ -65,12 +65,36 @@ def validate_delegation_grant_payload(
         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)
+        not_before = payload.get("not_before")
         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",
+                "expires_at must be greater than not_before",
             )
+        if created_at is not None and expires_at <= created_at:
+            raise AgentProtocolError(
+                "invalid_delegation",
+                "expires_at must be greater than created_at",
+            )
+
+
+def validate_delegation_query_request(request: dict[str, Any]) -> None:
+    """A delegation query MUST include at least one of `subject` or
+    `principal_id`. `limit` defaults to 20; services SHOULD cap it at 100."""
+    subject = request.get("subject")
+    principal_id = request.get("principal_id")
+    if subject is None and principal_id is None:
+        raise AgentProtocolError(
+            "invalid_delegation",
+            "query must include at least one of subject or principal_id",
+        )
+    if subject is not None:
+        validate_agent_id(subject)
+    if principal_id is not None:
+        _validate_https_url(principal_id, "principal_id")
+    limit = request.get("limit")
+    if limit is not None and (not isinstance(limit, int) or limit < 1):
+        raise AgentProtocolError("invalid_delegation", "limit must be a positive integer")
 
 
 def validate_delegation_revoke_payload(payload: DelegationRevokePayload) -> None:

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

@@ -1,7 +1,7 @@
 """Agent Discourse Protocol 1.0: kernel types, the room type system, and
 verification helpers.
 
-The protocol defines nine built-in event types. Every other event type is
+The protocol defines eleven built-in event types. Every other event type is
 declared per room as a schema-validated type definition, either inline or
 imported from a type pack. Hosts validate structure and permissions; they
 never need to understand application semantics.
@@ -32,12 +32,14 @@ from .identity import (
 
 DISCOURSE_PROTOCOL = "agent-discourse/1.0"
 
-# The nine built-in event types. All other types are room-defined.
+# The eleven built-in event types. All other types are room-defined.
 ROOM_CREATE = "room.create"
+ROOM_UPDATE = "room.update"
 ROOM_JOIN = "room.join"
 ROOM_JOIN_REVIEW = "room.join.review"
 ROOM_LEAVE = "room.leave"
 ROOM_MEMBER_ROLE_UPDATE = "room.member.role.update"
+ROOM_MEMBER_REMOVE = "room.member.remove"
 ROOM_CLOSE = "room.close"
 ROOM_CANCEL = "room.cancel"
 TYPE_DEFINE = "type.define"
@@ -45,16 +47,67 @@ MESSAGE_CREATE = "message.create"
 
 BUILTIN_EVENT_TYPES = {
     ROOM_CREATE,
+    ROOM_UPDATE,
     ROOM_JOIN,
     ROOM_JOIN_REVIEW,
     ROOM_LEAVE,
     ROOM_MEMBER_ROLE_UPDATE,
+    ROOM_MEMBER_REMOVE,
     ROOM_CLOSE,
     ROOM_CANCEL,
     TYPE_DEFINE,
     MESSAGE_CREATE,
 }
 
+# Built-in membership events. They carry the `signal` class: they anchor to
+# an accepted record but never contend for or advance the room head, so busy
+# rooms cannot starve joins, reviews, or other membership writes.
+MEMBERSHIP_EVENT_TYPES = (
+    ROOM_JOIN,
+    ROOM_JOIN_REVIEW,
+    ROOM_LEAVE,
+    ROOM_MEMBER_ROLE_UPDATE,
+    ROOM_MEMBER_REMOVE,
+)
+
+# Standard ADP error codes from the Section 20 table.
+DISCOURSE_ERROR_CODES = frozenset(
+    {
+        "invalid_event",
+        "invalid_event_hash",
+        "invalid_signature",
+        "invalid_actor",
+        "timestamp_out_of_window",
+        "nonce_not_greater",
+        "room_not_found",
+        "room_not_active",
+        "room_ended",
+        "permission_denied",
+        "approval_required",
+        "join_request_not_found",
+        "join_request_not_approved",
+        "join_request_role_mismatch",
+        "join_request_expired",
+        "member_banned",
+        "role_not_allowed",
+        "max_speakers_exceeded",
+        "membership_required",
+        "invalid_token",
+        "room_head_mismatch",
+        "base_record_mismatch",
+        "agent_status_not_found",
+        "rate_limited",
+        "payload_too_large",
+        "type_not_defined",
+        "type_disabled",
+        "payload_schema_violation",
+        "pack_unavailable",
+    }
+)
+
+# Hosts MUST reject events with more than this many `mentions` entries.
+MAX_MENTIONS = 32
+
 # Custom event types must not use these prefixes.
 RESERVED_TYPE_PREFIXES = ("room.", "type.")
 
@@ -171,6 +224,42 @@ def event_requires_room_id(event_type: str) -> bool:
     return event_type != ROOM_CREATE
 
 
+BuiltinEventClass = Literal["lifecycle", "signal", "control", "message"]
+
+_BUILTIN_EVENT_CLASSES: dict[str, BuiltinEventClass] = {
+    ROOM_CREATE: "lifecycle",
+    ROOM_UPDATE: "lifecycle",
+    ROOM_CLOSE: "lifecycle",
+    ROOM_CANCEL: "lifecycle",
+    ROOM_JOIN: "signal",
+    ROOM_JOIN_REVIEW: "signal",
+    ROOM_LEAVE: "signal",
+    ROOM_MEMBER_ROLE_UPDATE: "signal",
+    ROOM_MEMBER_REMOVE: "signal",
+    TYPE_DEFINE: "control",
+    MESSAGE_CREATE: "message",
+}
+
+
+def builtin_event_class(event_type: str) -> BuiltinEventClass | None:
+    """Section 13.2 class of a built-in type; ``None`` for room-defined types."""
+    return _BUILTIN_EVENT_CLASSES.get(event_type)
+
+
+def event_advances_room_head(event_type: str, registry: "TypeRegistry | None" = None) -> bool:
+    """Whether an accepted record of this type advances the room head and must
+    therefore match the current head when written (Section 6.1). Room
+    lifecycle, `message`-kind, and `control`-kind records advance the head;
+    `signal`-kind records — including the built-in membership events — only
+    anchor to an accepted record. Unknown custom types default to
+    head-advancing."""
+    builtin_class = builtin_event_class(event_type)
+    if builtin_class is not None:
+        return builtin_class != "signal"
+    definition = registry.get(event_type) if registry is not None else None
+    return definition is None or definition.get("kind") != "signal"
+
+
 def validate_discourse_envelope(envelope: Envelope) -> None:
     verify_envelope(envelope)
     event = envelope["event"]
@@ -222,8 +311,17 @@ def _validate_mentions(mentions: Any) -> None:
         return
     if not isinstance(mentions, list):
         raise AgentProtocolError("invalid_event", "mentions must be an Agent ID array")
+    if len(mentions) > MAX_MENTIONS:
+        raise AgentProtocolError("invalid_event", f"mentions must not exceed {MAX_MENTIONS} entries")
+    # Validate each entry before testing uniqueness: a non-string mention would
+    # otherwise raise a raw TypeError from set() instead of a clean protocol
+    # error.
+    seen: set[str] = set()
     for mention in mentions:
         validate_agent_id(mention)
+        if mention in seen:
+            raise AgentProtocolError("invalid_event", "mentions must be unique")
+        seen.add(mention)
 
 
 def validate_custom_event_type_name(name: str) -> None:
@@ -334,6 +432,12 @@ class TypeRegistry:
 
     def define(self, definition: dict[str, Any]) -> None:
         validate_type_def(definition)
+        existing = self._types.get(definition["type"])
+        if existing is not None and existing.get("kind") != definition.get("kind"):
+            raise AgentProtocolError(
+                "invalid_event",
+                f"type {definition['type']} cannot change kind on redefinition",
+            )
         self._types[definition["type"]] = definition
 
     def _import(self, declaration: dict[str, Any], packs: dict[str, dict[str, Any]]) -> None:
@@ -452,6 +556,44 @@ def validate_room_join_payload(payload: dict[str, Any]) -> None:
         )
 
 
+_ROOM_UPDATE_FIELDS = frozenset(
+    {"topic", "agenda", "guidance", "tags", "language", "policy", "start_time", "end_time"}
+)
+
+
+def validate_room_update_payload(payload: dict[str, Any]) -> None:
+    """Shape checks for a `room.update` payload. State-dependent rules — room
+    status, effective time ordering against the current contract — remain
+    host-side."""
+    if not payload:
+        raise AgentProtocolError("invalid_event", "room.update payload must not be empty")
+    for field in payload:
+        if field not in _ROOM_UPDATE_FIELDS:
+            raise AgentProtocolError(
+                "invalid_event", f"room.update payload field {field} is not updatable"
+            )
+    topic = payload.get("topic")
+    if topic is not None and not str(topic).strip():
+        raise AgentProtocolError("invalid_event", "room topic must not be empty")
+    start_time = payload.get("start_time")
+    end_time = payload.get("end_time")
+    if start_time is not None and end_time is not None and start_time >= end_time:
+        raise AgentProtocolError("invalid_event", "start_time must be before end_time")
+    policy = payload.get("policy") or {}
+    max_speakers = policy.get("max_speakers")
+    if max_speakers is not None and (not isinstance(max_speakers, int) or max_speakers < 1):
+        raise AgentProtocolError("invalid_event", "max_speakers must be a positive integer")
+
+
+def validate_room_member_remove_payload(payload: dict[str, Any]) -> None:
+    """Shape checks for a `room.member.remove` payload. Creator, self, and
+    membership checks remain host-side."""
+    validate_agent_id(payload.get("member"))
+    ban = payload.get("ban")
+    if ban is not None and not isinstance(ban, bool):
+        raise AgentProtocolError("invalid_event", "ban must be a boolean")
+
+
 def server_record_hash_payload(
     room_id: str,
     seq: int,
@@ -554,7 +696,15 @@ def can_submit_event(
         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}:
+    if event_type in {
+        ROOM_UPDATE,
+        ROOM_JOIN_REVIEW,
+        ROOM_MEMBER_ROLE_UPDATE,
+        ROOM_MEMBER_REMOVE,
+        ROOM_CLOSE,
+        ROOM_CANCEL,
+        TYPE_DEFINE,
+    }:
         return is_creator or role == "moderator"
     if event_type == MESSAGE_CREATE:
         return is_creator or role in ("moderator", "speaker")
@@ -576,7 +726,9 @@ def can_write_in_state(event_type: str, state: RoomState) -> bool:
             ROOM_JOIN,
             ROOM_JOIN_REVIEW,
             ROOM_MEMBER_ROLE_UPDATE,
+            ROOM_MEMBER_REMOVE,
             ROOM_LEAVE,
+            ROOM_UPDATE,
             TYPE_DEFINE,
             ROOM_CANCEL,
         }

agent_protocols-0.5.0/src/agent_protocols/errors.py

@@ -0,0 +1,6 @@
+class AgentProtocolError(ValueError):
+    def __init__(self, code: str, message: str, data: dict | None = None):
+        super().__init__(message)
+        self.code = code
+        # Structured error details, e.g. {"max_nonce": ...} on nonce_not_greater.
+        self.data = data

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

@@ -8,6 +8,7 @@ try:
 except ImportError:  # pragma: no cover
     requests = None  # type: ignore[assignment]
 
+from .delegation import validate_delegation_query_request
 from .identity import AgentId, Envelope
 
 
@@ -22,8 +23,14 @@ class ProfileClient:
     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 profile_events(
+        self, agent_id: AgentId, limit: int = 1, cursor: str | None = None
+    ) -> dict[str, Any]:
+        query = urlencode(
+            {key: value for key, value in {"limit": limit, "cursor": cursor}.items() if value is not None},
+            quote_via=quote,
+        )
+        return self._get(f"/v1/profiles/{agent_id}/events?{query}")
 
     def submit_profile_update(self, envelope: Envelope) -> dict[str, Any]:
         return self._post("/v1/profiles", envelope)
@@ -87,8 +94,30 @@ class DiscourseClient:
         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 my_rooms(
+        self,
+        jwt: str,
+        *,
+        status: str | None = None,
+        membership: 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,
+                    "membership": membership,
+                    "limit": limit,
+                    "cursor": cursor,
+                }.items()
+                if value is not None
+            },
+            quote_via=quote,
+        )
+        suffix = f"?{query}" if query else ""
+        return self._get(f"/v1/me/rooms{suffix}", 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)
@@ -192,6 +221,7 @@ class DelegationClient:
         return self._post("/v1/delegations", envelope)
 
     def query_delegations(self, request: dict[str, Any]) -> dict[str, Any]:
+        validate_delegation_query_request(request)
         return self._post("/v1/delegations/query", request)
 
     def _get(self, path: str) -> Any:

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

@@ -6,6 +6,7 @@ import json
 import re
 import time
 from dataclasses import dataclass
+from urllib.parse import urlparse
 from typing import Any, MutableMapping, Protocol
 
 import rfc8785
@@ -34,9 +35,11 @@ def agent_id_from_public_key(public_key: bytes) -> AgentId:
 
 
 def public_key_bytes(agent_id: AgentId) -> bytes:
+    if not isinstance(agent_id, str):
+        raise AgentProtocolError("invalid_agent_id", "agent id must be a string")
     if not agent_id.startswith(AGENT_ID_PREFIX):
         raise AgentProtocolError("invalid_agent_id", "agent id must start with did:agent:")
-    data = _base64url_decode_no_pad(agent_id[len(AGENT_ID_PREFIX):])
+    data = _base64url_decode(agent_id[len(AGENT_ID_PREFIX):])
     if len(data) != 32:
         raise AgentProtocolError("invalid_public_key", f"agent id public key must be 32 bytes, got {len(data)}")
     return data
@@ -114,7 +117,14 @@ class MemoryNonceStore:
         if record is not None:
             max_nonce, expires_at = record
             if expires_at > now_ms and nonce <= max_nonce:
-                raise AgentProtocolError("nonce_not_greater", f"nonce must be greater than accepted max nonce {max_nonce}")
+                # Services rejecting for this reason MUST return the effective
+                # maximum in the `Max-Seen-Nonce` response header; `data`
+                # carries it.
+                raise AgentProtocolError(
+                    "nonce_not_greater",
+                    f"nonce must be greater than accepted max nonce {max_nonce}",
+                    data={"max_nonce": max_nonce},
+                )
         self._records[actor] = (nonce, now_ms + ttl_ms)
         return nonce
 
@@ -215,6 +225,11 @@ def sign_event(private_key: Ed25519PrivateKey, event: Event) -> str:
 
 
 def sign_event_hash(private_key: Ed25519PrivateKey, event_hash: bytes) -> str:
+    """Signs a precomputed 32-byte event hash. Signing a digest supplied by
+    another component without seeing the event it commits to (blind signing)
+    is NOT RECOMMENDED: ``actor`` and all event content are inside the digest,
+    so a blind signer can be tricked into signing arbitrary events attributed
+    to its key. Prefer :func:`sign_event`."""
     return _base64url_encode(private_key.sign(_valid_event_hash_bytes(event_hash)))
 
 
@@ -302,6 +317,20 @@ def verify_request_jwt(token: str, *, audience: str, now_secs: int | None = None
     return claims
 
 
+def service_origin(url: str) -> str:
+    """Derives the request JWT ``aud`` from a request URL: the service origin —
+    scheme, host, and non-default port, with no path (Agent Identity Section 8)."""
+    parsed = urlparse(url)
+    if parsed.scheme not in ("https", "http") or not parsed.hostname:
+        raise AgentProtocolError("invalid_url", f"not an HTTP(S) URL: {url}")
+    host = parsed.hostname
+    port = parsed.port
+    default_port = 443 if parsed.scheme == "https" else 80
+    if port is None or port == default_port:
+        return f"{parsed.scheme}://{host}"
+    return f"{parsed.scheme}://{host}:{port}"
+
+
 def unix_ms() -> int:
     return int(time.time() * 1000)
 
@@ -320,14 +349,20 @@ def _base64url_encode(data: bytes) -> str:
 
 
 def _base64url_decode(value: str) -> bytes:
+    """Canonical base64url decoding: URL-safe alphabet, no padding, zero
+    trailing bits. Receivers MUST reject non-canonical encodings, otherwise
+    one value gains multiple distinct string forms and corrupts string-keyed
+    comparisons."""
+    if not re.fullmatch(r"[A-Za-z0-9_-]*", value):
+        raise AgentProtocolError("invalid_encoding", "expected canonical base64url without padding")
     padding = "=" * ((4 - len(value) % 4) % 4)
-    return base64.urlsafe_b64decode(value + padding)
-
-
-def _base64url_decode_no_pad(value: str) -> bytes:
-    if not re.fullmatch(r"[A-Za-z0-9_-]+", value):
-        raise AgentProtocolError("invalid_encoding", "expected base64url without padding")
-    return _base64url_decode(value)
+    try:
+        data = base64.urlsafe_b64decode(value + padding)
+    except (ValueError, TypeError) as exc:
+        raise AgentProtocolError("invalid_encoding", "expected canonical base64url without padding") from exc
+    if _base64url_encode(data) != value:
+        raise AgentProtocolError("invalid_encoding", "expected canonical base64url without padding")
+    return data
 
 
 def _valid_event_hash_bytes(event_hash: bytes) -> bytes:

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

@@ -35,7 +35,6 @@ 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"),
@@ -47,3 +46,13 @@ def materialize_profile(envelope: Envelope) -> AgentProfile:
         "updated_at": envelope["event"]["created_at"],
         "event_id": envelope["hash"],
     }
+
+
+def latest_profile_update(envelopes: list[Envelope]) -> Envelope | None:
+    """Selects the latest profile state from accepted update envelopes. Nonces
+    are strictly monotonic per Agent ID, so the latest profile is defined as
+    the accepted `profile.update` with the greatest `nonce` — deterministic
+    and independently checkable from event history alone."""
+    if not envelopes:
+        return None
+    return max(envelopes, key=lambda envelope: envelope["event"]["nonce"])

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-protocols
-Version: 0.4.1
+Version: 0.5.0
 Summary: Python SDK for Agent Identity, Agent Profile, Agent Delegation, and Agent Discourse protocols
 Author: LDCLabs
 License: MIT
@@ -42,6 +42,6 @@ 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 Profile has no `username` field: the Agent ID is the identity key, and the latest profile is the accepted `profile.update` with the greatest `nonce`.
 
-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`.
+ADP room writes declare a signed `base_seq` / `base_hash`: discussion and contract writes must match the current room head, while `signal`-kind writes — including the built-in membership events — only anchor to an accepted record and never contend for the 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.4.1 → agent_protocols-0.5.0}/tests/test_delegation.py

@@ -122,3 +122,45 @@ class DelegationTests(unittest.TestCase):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+class Revision20260704DelegationTests(unittest.TestCase):
+    def test_grant_expiry_checked_against_not_before_and_created_at(self):
+        from agent_protocols.delegation import validate_delegation_grant_payload
+        from agent_protocols.errors import AgentProtocolError
+        from agent_protocols.identity import AgentSigner
+
+        subject = AgentSigner.from_seed(bytes([46]) * 32).agent_id()
+        base = {
+            "id": "del_1",
+            "principal": {"id": "https://al.ink/yan"},
+            "subject": subject,
+            "scopes": ["inbox.screen"],
+        }
+
+        with self.assertRaisesRegex(AgentProtocolError, "greater than not_before"):
+            validate_delegation_grant_payload(
+                {**base, "not_before": 2000, "expires_at": 2000}, 1000
+            )
+        with self.assertRaisesRegex(AgentProtocolError, "greater than created_at"):
+            validate_delegation_grant_payload({**base, "expires_at": 1000}, 1000)
+        with self.assertRaisesRegex(AgentProtocolError, "greater than created_at"):
+            validate_delegation_grant_payload(
+                {**base, "not_before": 500, "expires_at": 800}, 1000
+            )
+        validate_delegation_grant_payload(
+            {**base, "not_before": 500, "expires_at": 1500}, 1000
+        )
+
+    def test_delegation_queries_require_subject_or_principal(self):
+        from agent_protocols.delegation import validate_delegation_query_request
+        from agent_protocols.errors import AgentProtocolError
+        from agent_protocols.identity import AgentSigner
+
+        subject = AgentSigner.from_seed(bytes([47]) * 32).agent_id()
+        validate_delegation_query_request({"subject": subject})
+        validate_delegation_query_request({"principal_id": "https://al.ink/yan", "limit": 20})
+        with self.assertRaisesRegex(AgentProtocolError, "at least one of subject or principal_id"):
+            validate_delegation_query_request({"status": "active"})
+        with self.assertRaisesRegex(AgentProtocolError, "positive integer"):
+            validate_delegation_query_request({"subject": subject, "limit": 0})

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

@@ -27,6 +27,7 @@ from agent_protocols.discourse import (
     can_accept_room_write,
     can_submit_event,
     can_write_in_state,
+    discourse_event,
     pack_map,
     room_create_event,
     server_record_hash,
@@ -41,6 +42,7 @@ from agent_protocols.discourse import (
     verify_server_record,
     verify_server_record_chain,
 )
+from agent_protocols import discourse
 from agent_protocols.errors import AgentProtocolError
 from agent_protocols.http_client import sse_events_url
 from agent_protocols.identity import AgentSigner, create_event
@@ -401,6 +403,118 @@ class DiscourseTests(unittest.TestCase):
             "https://api.example.com/v1/rooms/room123/events/live",
         )
 
+class Revision20260704Tests(unittest.TestCase):
+    def test_kernel_defines_eleven_builtins_with_membership_signals(self):
+        self.assertEqual(len(discourse.BUILTIN_EVENT_TYPES), 11)
+        self.assertIn("room.update", discourse.BUILTIN_EVENT_TYPES)
+        self.assertIn("room.member.remove", discourse.BUILTIN_EVENT_TYPES)
+
+        for membership in discourse.MEMBERSHIP_EVENT_TYPES:
+            self.assertEqual(discourse.builtin_event_class(membership), "signal")
+            self.assertFalse(discourse.event_advances_room_head(membership))
+        for advancing in (
+            discourse.ROOM_CREATE,
+            discourse.ROOM_UPDATE,
+            discourse.ROOM_CLOSE,
+            discourse.ROOM_CANCEL,
+            discourse.TYPE_DEFINE,
+            discourse.MESSAGE_CREATE,
+        ):
+            self.assertTrue(discourse.event_advances_room_head(advancing))
+        self.assertIsNone(discourse.builtin_event_class("review.finding"))
+
+        registry = discourse.TypeRegistry()
+        registry.define(
+            {
+                "type": "reaction.create",
+                "kind": "signal",
+                "title": "Reaction",
+                "schema": {"type": "object"},
+            }
+        )
+        self.assertFalse(discourse.event_advances_room_head("reaction.create", registry))
+        self.assertTrue(discourse.event_advances_room_head("unknown.type", registry))
+
+        self.assertIn("member_banned", discourse.DISCOURSE_ERROR_CODES)
+        self.assertIn("role_not_allowed", discourse.DISCOURSE_ERROR_CODES)
+        self.assertIn("max_speakers_exceeded", discourse.DISCOURSE_ERROR_CODES)
+
+    def test_room_update_and_member_remove_follow_moderator_rules(self):
+        for builtin in (discourse.ROOM_UPDATE, discourse.ROOM_MEMBER_REMOVE):
+            self.assertTrue(discourse.can_submit_event(builtin, {"role": "moderator"}))
+            self.assertTrue(discourse.can_submit_event(builtin, {"is_creator": True}))
+            self.assertFalse(discourse.can_submit_event(builtin, {"role": "speaker"}))
+            self.assertTrue(discourse.can_write_in_state(builtin, "scheduled"))
+            self.assertTrue(discourse.can_write_in_state(builtin, "active"))
+            self.assertFalse(discourse.can_write_in_state(builtin, "ended"))
+            self.assertFalse(discourse.can_write_in_state(builtin, "cancelled"))
+
+    def test_validates_room_update_payloads(self):
+        discourse.validate_room_update_payload(
+            {"topic": "New topic", "guidance": "", "end_time": 2000}
+        )
+        with self.assertRaisesRegex(AgentProtocolError, "must not be empty"):
+            discourse.validate_room_update_payload({})
+        with self.assertRaisesRegex(AgentProtocolError, "not updatable"):
+            discourse.validate_room_update_payload({"visibility": "private"})
+        with self.assertRaisesRegex(AgentProtocolError, "topic"):
+            discourse.validate_room_update_payload({"topic": "  "})
+        with self.assertRaisesRegex(AgentProtocolError, "before end_time"):
+            discourse.validate_room_update_payload({"start_time": 5, "end_time": 5})
+        with self.assertRaisesRegex(AgentProtocolError, "max_speakers"):
+            discourse.validate_room_update_payload({"policy": {"max_speakers": 0}})
+
+    def test_validates_room_member_remove_payloads(self):
+        member = AgentSigner.from_seed(bytes([41]) * 32).agent_id()
+        discourse.validate_room_member_remove_payload({"member": member})
+        discourse.validate_room_member_remove_payload({"member": member, "ban": True})
+        with self.assertRaises(AgentProtocolError):
+            discourse.validate_room_member_remove_payload({"member": "not-an-id"})
+        with self.assertRaisesRegex(AgentProtocolError, "ban must be a boolean"):
+            discourse.validate_room_member_remove_payload({"member": member, "ban": "yes"})
+
+    def test_mentions_are_capped_at_32_unique_agent_ids(self):
+        signer = AgentSigner.from_seed(bytes([42]) * 32)
+        others = [AgentSigner.from_seed(bytes([100 + index]) * 32).agent_id() for index in range(33)]
+
+        def envelope_with(mentions):
+            event = discourse_event(
+                MESSAGE_CREATE,
+                signer.agent_id(),
+                100,
+                1,
+                "room1",
+                1,
+                "room-create-head",
+                {"content_type": "text/plain", "content": "hi"},
+            )
+            event["mentions"] = mentions
+            return signer.sign_event(event)
+
+        validate_discourse_envelope(envelope_with(others[:32]))
+        with self.assertRaisesRegex(AgentProtocolError, "must not exceed 32"):
+            validate_discourse_envelope(envelope_with(others))
+        with self.assertRaisesRegex(AgentProtocolError, "unique"):
+            validate_discourse_envelope(envelope_with([others[0], others[0]]))
+        # A non-string mention yields a clean protocol error, not a raw
+        # TypeError from set() hashing.
+        with self.assertRaises(AgentProtocolError):
+            validate_discourse_envelope(envelope_with([{"not": "a string"}]))
+
+    def test_type_redefinition_cannot_change_kind(self):
+        definition = {
+            "type": "review.finding",
+            "kind": "message",
+            "title": "Finding",
+            "schema": {"type": "object"},
+        }
+        registry = discourse.TypeRegistry()
+        registry.define(definition)
+        registry.define({**definition, "title": "Finding v2"})
+        self.assertEqual(registry.get("review.finding")["title"], "Finding v2")
+        with self.assertRaisesRegex(AgentProtocolError, "cannot change kind"):
+            registry.define({**definition, "kind": "signal"})
+
 
 if __name__ == "__main__":
     unittest.main()

{agent_protocols-0.4.1 → agent_protocols-0.5.0}/tests/test_identity.py

@@ -131,3 +131,86 @@ class IdentityTests(unittest.TestCase):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+class Revision20260704IdentityTests(unittest.TestCase):
+    ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
+
+    def test_base64url_decoding_rejects_non_canonical_encodings(self):
+        from agent_protocols.errors import AgentProtocolError
+        from agent_protocols.identity import (
+            AGENT_ID_PREFIX,
+            AgentSigner,
+            create_event,
+            validate_agent_id,
+            verify_envelope,
+        )
+
+        signer = AgentSigner.from_seed(bytes([60]) * 32)
+        agent_id = signer.agent_id()
+        suffix = agent_id[len(AGENT_ID_PREFIX):]
+        validate_agent_id(agent_id)
+
+        # Padding characters are rejected even when the decoded bytes match.
+        with self.assertRaisesRegex(AgentProtocolError, "canonical base64url"):
+            validate_agent_id(f"{AGENT_ID_PREFIX}{suffix}==")
+
+        # Non-zero trailing bits give the same key a second string form:
+        # replace the final character with one sharing its used bits but
+        # different trailing bits (the last char of a 32-byte value uses 4 of
+        # its 6 bits).
+        index = self.ALPHABET.index(suffix[-1])
+        non_canonical = self.ALPHABET[(index & ~3) | ((index & 3) ^ 1)]
+        with self.assertRaisesRegex(AgentProtocolError, "canonical base64url"):
+            validate_agent_id(f"{AGENT_ID_PREFIX}{suffix[:-1]}{non_canonical}")
+
+        # Non-alphabet characters are rejected.
+        with self.assertRaisesRegex(AgentProtocolError, "canonical base64url"):
+            validate_agent_id(f"{AGENT_ID_PREFIX}{suffix[:-1]}+")
+
+        # Signatures must be canonical base64url too.
+        event = create_event(
+            "agent-profile/1.0",
+            "profile.update",
+            agent_id,
+            1000,
+            1,
+            {"id": agent_id, "name": "Agent"},
+        )
+        envelope = signer.sign_event(event)
+        tampered = {**envelope, "signature": envelope["signature"] + "="}
+        with self.assertRaisesRegex(AgentProtocolError, "canonical base64url"):
+            verify_envelope(tampered)
+
+    def test_service_origin_derives_request_jwt_audience(self):
+        from agent_protocols.errors import AgentProtocolError
+        from agent_protocols.identity import service_origin
+
+        self.assertEqual(
+            service_origin("https://api.example.com/v1/rooms/room1"),
+            "https://api.example.com",
+        )
+        self.assertEqual(
+            service_origin("https://api.example.com:8443/path?q=1"),
+            "https://api.example.com:8443",
+        )
+        self.assertEqual(
+            service_origin("https://API.Example.com:443/"),
+            "https://api.example.com",
+        )
+        with self.assertRaises(AgentProtocolError):
+            service_origin("not a url")
+        with self.assertRaises(AgentProtocolError):
+            service_origin("ftp://example.com")
+
+    def test_nonce_not_greater_errors_carry_the_effective_maximum(self):
+        from agent_protocols.errors import AgentProtocolError
+        from agent_protocols.identity import AgentSigner, MemoryNonceStore
+
+        actor = AgentSigner.from_seed(bytes([61]) * 32).agent_id()
+        store = MemoryNonceStore()
+        store.check_and_update(actor, 7, 1000, 1000)
+        with self.assertRaises(AgentProtocolError) as caught:
+            store.check_and_update(actor, 7, 1100, 1000)
+        self.assertEqual(caught.exception.code, "nonce_not_greater")
+        self.assertEqual(caught.exception.data, {"max_nonce": 7})

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

@@ -1,7 +1,12 @@
 import unittest
 
 from agent_protocols.identity import AgentSigner
-from agent_protocols.profile import materialize_profile, profile_update_event, validate_profile_update
+from agent_protocols.profile import (
+    latest_profile_update,
+    materialize_profile,
+    profile_update_event,
+    validate_profile_update,
+)
 
 
 class ProfileTests(unittest.TestCase):
@@ -28,14 +33,14 @@ class ProfileTests(unittest.TestCase):
 
         self.assertEqual(profile["id"], signer.agent_id())
         self.assertEqual(profile["name"], "ResearchAgent-v3")
-        self.assertIsNone(profile["username"])
+        self.assertNotIn("username", profile)
         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"])
 
-    def test_does_not_materialize_unconfirmed_payload_username(self):
+    def test_does_not_materialize_the_removed_username_field(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))
@@ -43,7 +48,26 @@ class ProfileTests(unittest.TestCase):
         profile = materialize_profile(envelope)
 
         self.assertEqual(profile["id"], signer.agent_id())
-        self.assertIsNone(profile["username"])
+        self.assertNotIn("username", profile)
+
+    def test_latest_profile_update_picks_greatest_nonce(self):
+        signer = AgentSigner.from_seed(bytes([16]) * 32)
+        envelopes = [
+            signer.sign_event(
+                profile_update_event(
+                    signer.agent_id(),
+                    1_779_753_600_000 + nonce,
+                    nonce,
+                    {"id": signer.agent_id(), "name": f"Agent-v{nonce}"},
+                )
+            )
+            for nonce in (3, 1, 2)
+        ]
+
+        self.assertIsNone(latest_profile_update([]))
+        latest = latest_profile_update(envelopes)
+        self.assertEqual(latest["event"]["nonce"], 3)
+        self.assertEqual(materialize_profile(latest)["name"], "Agent-v3")
 
     def test_rejects_actor_payload_mismatch(self):
         signer = AgentSigner.from_seed(bytes([12]) * 32)

agent_protocols-0.4.1/src/agent_protocols/errors.py

@@ -1,4 +0,0 @@
-class AgentProtocolError(ValueError):
-    def __init__(self, code: str, message: str):
-        super().__init__(message)
-        self.code = code