feat: send change reasons from all SDKs (#115)

Rust, Python and TypeScript clients gain with_reason / withReason, a derived client that sends the percent-encoded Everruns-Change-Reason header so the server records the reason in entity change history. Blank reasons send no header; the original client is unchanged.

Author: chaliy

README.md

@@ -189,6 +189,29 @@ client = Everruns(api_key="evr_pat_...", org_id="org_...")
 const client = new Everruns({ apiKey: "evr_pat_...", orgId: "org_..." });
 ```
 
+## Change Reasons
+
+Mutations can carry a reason that the server records in the changed entity's
+history. Derive a client scoped to the reason; the original stays unchanged:
+
+```rust
+// Rust
+client.with_reason("retire the unused agent").agents().delete("agent_123").await?;
+```
+
+```python
+# Python
+await client.with_reason("retire the unused agent").agents.delete("agent_123")
+```
+
+```typescript
+// TypeScript
+await client.withReason("retire the unused agent").agents.delete("agent_123");
+```
+
+The reason is sent as the `Everruns-Change-Reason` header, UTF-8
+percent-encoded; the server accepts up to 1000 characters.
+
 ## Error Handling
 
 Consistent error types across all SDKs:

python/README.md

@@ -119,6 +119,24 @@ Or with an explicit token and organization:
 client = Everruns(api_key="evr_pat_...", org_id="org_...")
 ```
 
+## Change Reasons
+
+Record why a change was made. `with_reason` derives a client that sends the
+reason with every request it makes; the server stores it in the changed
+entity's history. The derived client shares the original's connection, and the
+original stays unchanged:
+
+```python
+await client.with_reason("retire the unused agent").agents.delete("agent_123")
+
+scoped = client.with_reason("rotate prompts for the Q3 launch")
+await scoped.agents.apply(agent_id, "assistant", "You are concise.")
+```
+
+The reason travels in the `Everruns-Change-Reason` header, UTF-8
+percent-encoded. A blank reason sends no header. The server trims the reason and rejects it with HTTP 400 (`invalid_change_reason`) when it is longer than 1000 characters, contains control characters other than newline and tab, or looks like it contains a credential. Closing a derived
+client is a no-op; close the client it came from.
+
 ## Agent Versions
 
 ```python

python/everruns_sdk/__init__.py

@@ -9,7 +9,7 @@
 """
 
 from everruns_sdk.auth import ApiKey
-from everruns_sdk.client import Everruns
+from everruns_sdk.client import CHANGE_REASON_HEADER, MAX_CHANGE_REASON_CHARS, Everruns
 from everruns_sdk.errors import (
     ApiError,
     AuthenticationError,
@@ -94,6 +94,8 @@
 
 __all__ = [
     "Everruns",
+    "CHANGE_REASON_HEADER",
+    "MAX_CHANGE_REASON_CHARS",
     "ApiKey",
     "EverrunsError",
     "ApiError",

python/everruns_sdk/client.py

@@ -5,7 +5,7 @@
 import asyncio
 import os
 from typing import Any, Literal, Optional
-from urllib.parse import urlencode
+from urllib.parse import quote, urlencode
 
 import httpx
 
@@ -79,6 +79,23 @@
 
 DEFAULT_BASE_URL = "https://app.everruns.com/api"
 
+#: Request header carrying a change reason; the server records it in the
+#: changed entity's history.
+CHANGE_REASON_HEADER = "Everruns-Change-Reason"
+
+#: Longest change reason the server accepts, in characters.
+MAX_CHANGE_REASON_CHARS = 1000
+
+
+def _encode_change_reason(reason: str) -> str:
+    """Percent-encode a change reason as UTF-8.
+
+    Only RFC 3986 unreserved characters stay bare: the encoding the server's
+    decoder and the Everruns CLI use. ``+`` is encoded rather than read as a
+    space.
+    """
+    return quote(reason, safe="", encoding="utf-8")
+
 
 def _is_html_response(body: str) -> bool:
     """Check if the body looks like an HTML response."""
@@ -149,6 +166,9 @@ def __init__(
 
         self._api_key = ApiKey(api_key)
         self._org_id = _validate_org_id(org_id)
+        # Set only on clients derived with `with_reason`, which share `_client`.
+        self._change_reason: Optional[str] = None
+        self._owns_client = True
         # Ensure base URL has trailing slash for correct URL joining.
         # httpx follows RFC 3986: without trailing slash, relative paths
         # replace the last path segment instead of appending.
@@ -161,6 +181,32 @@ def __init__(
             timeout=30.0,
         )
 
+    def with_reason(self, reason: str) -> "Everruns":
+        """Derive a client that records ``reason`` as the change reason of every request.
+
+        The derived client shares this client's connection pool and settings;
+        this client is left unchanged. The reason travels in the
+        ``Everruns-Change-Reason`` header, UTF-8 percent-encoded, and lands in
+        the changed entity's history. A blank reason sends no header.
+
+        The server trims the reason and rejects (HTTP 400,
+        ``invalid_change_reason``) one longer than ``MAX_CHANGE_REASON_CHARS``
+        characters, one with control characters other than newline and tab,
+        or one that looks like it contains a credential.
+
+        The derived client does not own the connection: closing it is a no-op;
+        close the client it was derived from.
+
+        Example:
+            >>> await client.with_reason("retire the unused agent").agents.delete("agent_123")
+        """
+        derived = object.__new__(Everruns)
+        derived.__dict__.update(self.__dict__)
+        trimmed = reason.strip()
+        derived._change_reason = _encode_change_reason(trimmed) if trimmed else None
+        derived._owns_client = False
+        return derived
+
     @property
     def agents(self) -> AgentsClient:
         """Get the agents client."""
@@ -231,23 +277,31 @@ def _auth_headers(self, *, content_type: Optional[str] = "application/json") ->
         headers = {"Authorization": self._api_key.value}
         if content_type is not None:
             headers["Content-Type"] = content_type
+        headers.update(self._reason_headers())
         if self._org_id is not None:
             headers["X-Org-Id"] = self._org_id
         return headers
 
+    def _reason_headers(self) -> dict[str, str]:
+        # Per request, because derived clients share one httpx client whose
+        # default headers carry no reason.
+        if self._change_reason is None:
+            return {}
+        return {CHANGE_REASON_HEADER: self._change_reason}
+
     async def _get(self, path: str) -> Any:
-        resp = await self._client.get(self._url(path))
+        resp = await self._client.get(self._url(path), headers=self._reason_headers())
         return await self._handle_response(resp)
 
     async def _get_text(self, path: str) -> str:
-        resp = await self._client.get(self._url(path))
+        resp = await self._client.get(self._url(path), headers=self._reason_headers())
         if resp.is_success:
             return resp.text
         await self._raise_error(resp)
         return ""  # unreachable
 
     async def _post(self, path: str, data: Any) -> Any:
-        resp = await self._client.post(self._url(path), json=data)
+        resp = await self._client.post(self._url(path), json=data, headers=self._reason_headers())
         return await self._handle_response(resp)
 
     async def _post_text(self, path: str, content: str) -> Any:
@@ -259,25 +313,25 @@ async def _post_text(self, path: str, content: str) -> Any:
         return await self._handle_response(resp)
 
     async def _patch(self, path: str, data: Any) -> Any:
-        resp = await self._client.patch(self._url(path), json=data)
+        resp = await self._client.patch(self._url(path), json=data, headers=self._reason_headers())
         return await self._handle_response(resp)
 
     async def _put(self, path: str, data: Any) -> Any:
-        resp = await self._client.put(self._url(path), json=data)
+        resp = await self._client.put(self._url(path), json=data, headers=self._reason_headers())
         return await self._handle_response(resp)
 
     async def _put_empty(self, path: str) -> None:
-        resp = await self._client.put(self._url(path))
+        resp = await self._client.put(self._url(path), headers=self._reason_headers())
         if not resp.is_success:
             await self._raise_error(resp)
 
     async def _delete(self, path: str) -> None:
-        resp = await self._client.delete(self._url(path))
+        resp = await self._client.delete(self._url(path), headers=self._reason_headers())
         if not resp.is_success:
             await self._raise_error(resp)
 
     async def _delete_json(self, path: str) -> Any:
-        resp = await self._client.delete(self._url(path))
+        resp = await self._client.delete(self._url(path), headers=self._reason_headers())
         return await self._handle_response(resp)
 
     async def _handle_response(self, resp: httpx.Response) -> Any:
@@ -299,8 +353,9 @@ async def _raise_error(self, resp: httpx.Response) -> None:
         raise ApiError.from_response(resp.status_code, body)
 
     async def close(self) -> None:
-        """Close the HTTP client."""
-        await self._client.aclose()
+        """Close the HTTP client (a no-op on a client derived with ``with_reason``)."""
+        if self._owns_client:
+            await self._client.aclose()
 
     async def __aenter__(self) -> "Everruns":
         return self

python/tests/test_client.py

@@ -152,6 +152,74 @@ async def test_client_sends_org_id_header():
     assert route.calls[0].request.headers["X-Org-Id"] == "org_123"
 
 
+@pytest.mark.asyncio
+@respx.mock
+async def test_with_reason_sends_encoded_change_reason_header():
+    route = respx.delete("https://app.everruns.com/api/v1/agents/agent_1").mock(
+        return_value=httpx.Response(204)
+    )
+
+    client = Everruns(api_key="evr_test_key", org_id="org_123")
+    try:
+        await client.with_reason("  retire \u00fcnused agent \u2713 ").agents.delete("agent_1")
+    finally:
+        await client.close()
+
+    request = route.calls[0].request
+    assert request.headers["Everruns-Change-Reason"] == "retire%20%C3%BCnused%20agent%20%E2%9C%93"
+    assert request.headers["X-Org-Id"] == "org_123"
+    assert request.headers["Authorization"]
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_with_reason_covers_text_bodies():
+    route = respx.post("https://app.everruns.com/api/v1/agents/import").mock(
+        return_value=httpx.Response(200, json=_agent_response())
+    )
+
+    client = Everruns(api_key="evr_test_key")
+    try:
+        await client.with_reason("a+b/c").agents.import_agent("name: a")
+    finally:
+        await client.close()
+
+    assert route.calls[0].request.headers["Everruns-Change-Reason"] == "a%2Bb%2Fc"
+
+
+@pytest.mark.asyncio
+@respx.mock
+async def test_original_client_sends_no_change_reason():
+    route = respx.delete("https://app.everruns.com/api/v1/agents/agent_1").mock(
+        return_value=httpx.Response(204)
+    )
+
+    client = Everruns(api_key="evr_test_key")
+    derived = client.with_reason("only on the derived client")
+    try:
+        await client.agents.delete("agent_1")
+        await derived.close()  # no-op: the derived client does not own the connection
+        await client.with_reason("   ").agents.delete("agent_1")
+    finally:
+        await client.close()
+
+    assert route.call_count == 2
+    for call in route.calls:
+        assert "Everruns-Change-Reason" not in call.request.headers
+    assert derived._client is client._client
+
+
+def test_change_reason_encoding_matches_server_decoder():
+    from everruns_sdk.client import _encode_change_reason
+
+    assert _encode_change_reason("make it kid friendly \u2713") == (
+        "make%20it%20kid%20friendly%20%E2%9C%93"
+    )
+    assert _encode_change_reason("a+b/c?d=e&f") == "a%2Bb%2Fc%3Fd%3De%26f"
+    assert _encode_change_reason("line\nnext") == "line%0Anext"
+    assert _encode_change_reason("Az09-_.~") == "Az09-_.~"
+
+
 def test_capabilities_subclient():
     """Test that capabilities sub-client is available."""
     client = Everruns(api_key="evr_test_key")

rust/README.md

@@ -191,6 +191,27 @@ let client = Everruns::builder()
     .build()?;
 ```
 
+## Change Reasons
+
+Record why a change was made. `with_reason` derives a client that sends the
+reason with every request it makes; the server stores it in the changed
+entity's history. The derived client shares the original's connection pool, and
+the original stays unchanged:
+
+```rust
+client
+    .with_reason("retire the unused agent")
+    .agents()
+    .delete("agent_123")
+    .await?;
+
+let scoped = client.with_reason("rotate prompts for the Q3 launch");
+scoped.agents().apply(&id, "assistant", "You are concise.").await?;
+```
+
+The reason travels in the `Everruns-Change-Reason` header, UTF-8
+percent-encoded. A blank reason sends no header. The server trims the reason and rejects it with HTTP 400 (`invalid_change_reason`) when it is longer than 1000 characters, contains control characters other than newline and tab, or looks like it contains a credential.
+
 ## Streaming Events
 
 The SDK supports SSE streaming with automatic reconnection: