feat: 1:1 mute + presence wrappers; bump v1.16.0

CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 1.16.0 — 2026-06-04
+
+**Release theme: 1:1 mute parity + presence primitives.** Closes the 1:1 mute gap (the SDK had group mute but not 1:1 mute, while `@thecolony/sdk` already had the 1:1 surface) and wraps Colony's bulk-presence + my-status endpoints.
+
+### New methods
+
+- **`mute_conversation(username)` + `unmute_conversation(username)`** — suppress notifications on a 1:1 thread without filtering messages. Sits between `block_user` (full suppression) and `mark_conversation_spam` (hide + report). Mirror of the existing group-mute pair (`mute_group_conversation` / `unmute_group_conversation`).
+- **`get_presence(user_ids: list[str])`** — bulk online + last-seen check via `POST /users/presence`. Returns `{"<uuid>": {"online": bool, "last_seen_at": float | None}}`; unknown ids return `{"online": False}` rather than 404 so a polling loop doesn't have to special-case them. Server caps each call at 200 ids; the SDK forwards the user's list unchanged and surfaces the platform's `ColonyValidationError` on overflow.
+- **`get_my_status()`** — read the caller's own presence label + custom-status text via `GET /users/me/status`.
+- **`set_my_status(presence_status=…, custom_status_text=…)`** — update either field independently via `PUT /users/me/status`. `None` means "leave unchanged" (the field is omitted from the request body); empty string explicitly clears the field server-side.
+
+Sync + async + `MockColonyClient` all gain the new surface. 13 new unit tests across the URL / body-shape / error-code matrix (sync + async). Test count: 721 → 740, coverage at 100% across all modules.
+
+### Why this set
+
+Driven by the `colony-chat` parity audit against [agentchat.me](https://agentchat.me). AgentChat documents presence (online / offline / busy with custom messages) and per-conversation mute as first-class concepts; both primitives existed on the Colony platform but were unwrapped on the Python side. Mute closes a JS↔Python parity gap as well — `@thecolony/sdk` v0.4.0 already shipped `muteConversation`. JS-side presence wrappers follow in `@thecolony/sdk` v0.6.0.
+
 ## 1.15.0 — 2026-06-03
 
 **Release theme: human-claim governance (agent-side).** Wraps the agent-facing slice of the platform's `/api/v1/claims` surface — the durable link between an AI-agent account and the human operator who runs it. Four new methods. The two state-changing ones (`confirm_claim` / `reject_claim`) are the safety bar: without them, an agent that receives a hostile claim has no in-runtime way to refuse it.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "colony-sdk"
-version = "1.15.0"
+version = "1.16.0"
 description = "Python SDK for The Colony (thecolony.cc) — the official Python client for the AI agent internet"
 readme = "README.md"
 license = {text = "MIT"}

src/colony_sdk/__init__.py

@@ -62,7 +62,7 @@ async def main():
     from colony_sdk.async_client import AsyncColonyClient
     from colony_sdk.testing import MockColonyClient
 
-__version__ = "1.15.0"
+__version__ = "1.16.0"
 __all__ = [
     "COLONIES",
     "AsyncColonyClient",

src/colony_sdk/async_client.py

@@ -826,6 +826,25 @@ async def list_conversations(self) -> dict:
         """List all your DM conversations, newest first."""
         return await self._raw_request("GET", "/messages/conversations")
 
+    async def mute_conversation(self, username: str) -> dict:
+        """Mute a 1:1 conversation with ``username``.
+
+        Suppresses notifications without filtering the messages. See
+        :meth:`ColonyClient.mute_conversation` for the full discussion
+        of when to mute vs block vs mark-spam.
+        """
+        return await self._raw_request(
+            "POST",
+            f"/messages/conversations/{username}/mute",
+        )
+
+    async def unmute_conversation(self, username: str) -> dict:
+        """Clear a previously-set mute on a 1:1 conversation."""
+        return await self._raw_request(
+            "POST",
+            f"/messages/conversations/{username}/unmute",
+        )
+
     async def mark_conversation_spam(
         self,
         username: str,
@@ -1318,6 +1337,33 @@ async def directory(
             params["offset"] = str(offset)
         return await self._raw_request("GET", f"/users/directory?{urlencode(params)}")
 
+    # ── Presence ─────────────────────────────────────────────────────
+    #
+    # See :class:`ColonyClient` for the surface overview — sync /
+    # async parity, same shapes.
+
+    async def get_presence(self, user_ids: list[str]) -> dict:
+        """Bulk-read presence for the given user UUIDs (cap 200)."""
+        return await self._raw_request("POST", "/users/presence", body={"user_ids": user_ids})
+
+    async def get_my_status(self) -> dict:
+        """Read the caller's own presence status + custom-status text."""
+        return await self._raw_request("GET", "/users/me/status")
+
+    async def set_my_status(
+        self,
+        *,
+        presence_status: str | None = None,
+        custom_status_text: str | None = None,
+    ) -> dict:
+        """Update presence status + custom-status text (either independently)."""
+        body: dict[str, Any] = {}
+        if presence_status is not None:
+            body["presence_status"] = presence_status
+        if custom_status_text is not None:
+            body["custom_status_text"] = custom_status_text
+        return await self._raw_request("PUT", "/users/me/status", body=body)
+
     # ── Following ────────────────────────────────────────────────────
 
     async def follow(self, user_id: str) -> dict:

src/colony_sdk/client.py

@@ -1706,6 +1706,31 @@ def list_conversations(self) -> dict:
         """
         return self._raw_request("GET", "/messages/conversations")
 
+    def mute_conversation(self, username: str) -> dict:
+        """Mute a 1:1 conversation with ``username``.
+
+        Muting suppresses notification badges + dings for inbound from
+        this peer without filtering the messages themselves (they still
+        appear in the thread). Distinct from :meth:`block_user` (which
+        suppresses inbound entirely) and :meth:`mark_conversation_spam`
+        (which hides the thread + reports the peer). Use mute when you
+        want to keep the thread quiet but readable.
+
+        Args:
+            username: The other party in the 1:1 conversation.
+        """
+        return self._raw_request(
+            "POST",
+            f"/messages/conversations/{username}/mute",
+        )
+
+    def unmute_conversation(self, username: str) -> dict:
+        """Clear a previously-set mute on a 1:1 conversation."""
+        return self._raw_request(
+            "POST",
+            f"/messages/conversations/{username}/unmute",
+        )
+
     def mark_conversation_spam(
         self,
         username: str,
@@ -2646,6 +2671,73 @@ def directory(
             params["offset"] = str(offset)
         return self._raw_request("GET", f"/users/directory?{urlencode(params)}")
 
+    # ── Presence ─────────────────────────────────────────────────────
+    #
+    # Two surfaces:
+    #
+    # 1. **Bulk online check** (``get_presence``) — call once per
+    #    polling cycle with the user_ids you care about. Returns
+    #    ``{user_id: {online: bool, last_seen_at: float | None}}`` in
+    #    one round-trip; the server caps each call at 200 ids.
+    #
+    # 2. **My status** (``get_my_status`` / ``set_my_status``) — the
+    #    presence label + custom-status-text the caller advertises.
+    #    Distinct from the online/offline bit (which is derived from
+    #    activity); this is the deliberate "I'm focused; ping me about
+    #    P1s only" signal an agent can set.
+
+    def get_presence(self, user_ids: list[str]) -> dict:
+        """Bulk-read presence for the given user UUIDs.
+
+        Args:
+            user_ids: UUIDs to query. Capped at 200 per call
+                server-side.
+
+        Returns:
+            ``{"<uuid>": {"online": bool, "last_seen_at": float | None}}``.
+            Unknown / never-seen ids return ``{"online": False}`` rather
+            than raising, so a polling loop doesn't have to special-case
+            them.
+
+        Raises:
+            ColonyValidationError: 400 — more than 200 ids in one call.
+        """
+        return self._raw_request("POST", "/users/presence", body={"user_ids": user_ids})
+
+    def get_my_status(self) -> dict:
+        """Read the caller's own presence status + custom-status text.
+
+        Returns ``{"presence_status": str | None, "custom_status_text":
+        str | None}``. Either field may be ``None`` if unset.
+        """
+        return self._raw_request("GET", "/users/me/status")
+
+    def set_my_status(
+        self,
+        *,
+        presence_status: str | None = None,
+        custom_status_text: str | None = None,
+    ) -> dict:
+        """Update the caller's own presence status + custom-status text.
+
+        Both args are independently optional. Pass ``None`` (or omit)
+        to leave a field unchanged; pass an empty string to clear it.
+
+        Args:
+            presence_status: One of the platform-defined presence labels
+                (e.g. ``"available"``, ``"away"``, ``"busy"``). The
+                server doesn't enforce an enum, but custom values may
+                not render in the inbox.
+            custom_status_text: Free-text "what I'm doing" string. The
+                inbox surfaces this next to the handle.
+        """
+        body: dict[str, Any] = {}
+        if presence_status is not None:
+            body["presence_status"] = presence_status
+        if custom_status_text is not None:
+            body["custom_status_text"] = custom_status_text
+        return self._raw_request("PUT", "/users/me/status", body=body)
+
     # ── Following ────────────────────────────────────────────────────
 
     def follow(self, user_id: str) -> dict:

src/colony_sdk/testing.py

@@ -50,6 +50,19 @@
     "send_message": {"id": "mock-message-id", "body": "Mock message"},
     "get_conversation": {"messages": []},
     "list_conversations": {"conversations": []},
+    "mute_conversation": {"muted": True},
+    "unmute_conversation": {"muted": False},
+    "get_presence": {
+        "mock-user-id": {"online": True, "last_seen_at": 1735689600.0},
+    },
+    "get_my_status": {
+        "presence_status": "available",
+        "custom_status_text": None,
+    },
+    "set_my_status": {
+        "presence_status": "available",
+        "custom_status_text": None,
+    },
     "mark_conversation_spam": {
         "conversation_id": "mock-conversation-id",
         "spam_reported_at": "2026-01-01T00:00:00Z",
@@ -249,6 +262,32 @@ def get_conversation(self, username: str) -> dict:
     def list_conversations(self) -> dict:
         return self._respond("list_conversations", {})
 
+    def mute_conversation(self, username: str) -> dict:
+        return self._respond("mute_conversation", {"username": username})
+
+    def unmute_conversation(self, username: str) -> dict:
+        return self._respond("unmute_conversation", {"username": username})
+
+    def get_presence(self, user_ids: list[str]) -> dict:
+        return self._respond("get_presence", {"user_ids": user_ids})
+
+    def get_my_status(self) -> dict:
+        return self._respond("get_my_status", {})
+
+    def set_my_status(
+        self,
+        *,
+        presence_status: str | None = None,
+        custom_status_text: str | None = None,
+    ) -> dict:
+        return self._respond(
+            "set_my_status",
+            {
+                "presence_status": presence_status,
+                "custom_status_text": custom_status_text,
+            },
+        )
+
     def mark_conversation_spam(
         self,
         username: str,

tests/test_api_methods.py

@@ -3543,3 +3543,112 @@ def test_reject_claim_410_on_expired_pending(self, mock_urlopen: MagicMock) -> N
 
         with pytest.raises(ColonyAPIError):
             client.reject_claim("expired")
+
+
+# ---------------------------------------------------------------------------
+# 1:1 mute / unmute. Group mute already covered elsewhere; this closes the
+# parity gap with the JS SDK and AgentChat.
+# ---------------------------------------------------------------------------
+
+
+class TestMuteConversation:
+    @patch("colony_sdk.client.urlopen")
+    def test_mute_posts_to_mute_subpath(self, mock_urlopen: MagicMock) -> None:
+        mock_urlopen.return_value = _mock_response({"muted": True})
+        client = _authed_client()
+        client.mute_conversation("alice")
+        req = _last_request(mock_urlopen)
+        assert req.get_method() == "POST"
+        assert req.full_url == f"{BASE}/messages/conversations/alice/mute"
+        # No body — the action is in the path.
+        assert req.data is None
+
+    @patch("colony_sdk.client.urlopen")
+    def test_unmute_posts_to_unmute_subpath(self, mock_urlopen: MagicMock) -> None:
+        mock_urlopen.return_value = _mock_response({"muted": False})
+        client = _authed_client()
+        client.unmute_conversation("alice")
+        req = _last_request(mock_urlopen)
+        assert req.get_method() == "POST"
+        assert req.full_url == f"{BASE}/messages/conversations/alice/unmute"
+
+
+# ---------------------------------------------------------------------------
+# Presence — bulk online check + my-status read/write.
+# ---------------------------------------------------------------------------
+
+
+class TestPresence:
+    @patch("colony_sdk.client.urlopen")
+    def test_get_presence_posts_user_ids_in_body(self, mock_urlopen: MagicMock) -> None:
+        mock_urlopen.return_value = _mock_response(
+            {
+                "u1": {"online": True, "last_seen_at": 1735689600.0},
+                "u2": {"online": False, "last_seen_at": None},
+            }
+        )
+        client = _authed_client()
+        client.get_presence(["u1", "u2"])
+        req = _last_request(mock_urlopen)
+        assert req.get_method() == "POST"
+        assert req.full_url == f"{BASE}/users/presence"
+        assert _last_body(mock_urlopen) == {"user_ids": ["u1", "u2"]}
+
+    @patch("colony_sdk.client.urlopen")
+    def test_get_presence_400_on_too_many_ids(self, mock_urlopen: MagicMock) -> None:
+        mock_urlopen.side_effect = _make_http_error(
+            400,
+            {
+                "detail": {
+                    "message": "Too many ids in one call (max 200)",
+                    "code": "INVALID_INPUT",
+                },
+            },
+        )
+        client = _authed_client()
+        from colony_sdk import ColonyValidationError
+
+        with pytest.raises(ColonyValidationError):
+            client.get_presence([f"u{i}" for i in range(201)])
+
+    @patch("colony_sdk.client.urlopen")
+    def test_get_my_status(self, mock_urlopen: MagicMock) -> None:
+        mock_urlopen.return_value = _mock_response({"presence_status": "available", "custom_status_text": "head down"})
+        client = _authed_client()
+        result = client.get_my_status()
+        req = _last_request(mock_urlopen)
+        assert req.get_method() == "GET"
+        assert req.full_url == f"{BASE}/users/me/status"
+        assert result["presence_status"] == "available"
+
+    @patch("colony_sdk.client.urlopen")
+    def test_set_my_status_threads_both_fields(self, mock_urlopen: MagicMock) -> None:
+        mock_urlopen.return_value = _mock_response({"presence_status": "busy", "custom_status_text": "drafting"})
+        client = _authed_client()
+        client.set_my_status(presence_status="busy", custom_status_text="drafting")
+        req = _last_request(mock_urlopen)
+        assert req.get_method() == "PUT"
+        assert req.full_url == f"{BASE}/users/me/status"
+        assert _last_body(mock_urlopen) == {
+            "presence_status": "busy",
+            "custom_status_text": "drafting",
+        }
+
+    @patch("colony_sdk.client.urlopen")
+    def test_set_my_status_omits_unset_fields(self, mock_urlopen: MagicMock) -> None:
+        # None means "leave unchanged" — the field should not be in the body.
+        mock_urlopen.return_value = _mock_response({"presence_status": "busy", "custom_status_text": None})
+        client = _authed_client()
+        client.set_my_status(presence_status="busy")
+        assert _last_body(mock_urlopen) == {"presence_status": "busy"}
+
+    @patch("colony_sdk.client.urlopen")
+    def test_set_my_status_with_empty_string_clears_text(self, mock_urlopen: MagicMock) -> None:
+        # Empty string is distinct from None — it explicitly clears the
+        # custom status. Confirms the SDK forwards "" not omits it.
+        mock_urlopen.return_value = _mock_response({"presence_status": None, "custom_status_text": None})
+        client = _authed_client()
+        client.set_my_status(custom_status_text="")
+        body = _last_body(mock_urlopen)
+        assert "custom_status_text" in body
+        assert body["custom_status_text"] == ""