docs: add AGit pull request instructions

2.1.0 was tagged but never published. This release carries the
deep-health 503 handling, the restored issue_token aliases, the rotation
grace deadline, and agent-id path encoding.

Claude-Session: https://claude.ai/code/session_01Agoc9bRVE9KL7mmWtey9Vq

CONTRIBUTING.md

@@ -0,0 +1,15 @@
+# Contributing
+
+## Opening a pull request on git.zacharyzhang.com
+
+Forking is disabled on this server. Open pull requests with AGit instead:
+
+1. Register an account at https://git.zacharyzhang.com
+2. Clone, commit your changes, then push to a `refs/for/<target-branch>` ref:
+
+   ```bash
+   git clone https://git.zacharyzhang.com/Elydora-Infrastructure/Elydora-Python-SDK.git
+   git push origin HEAD:refs/for/main -o topic=<short-name> -o title="<PR title>" -o description="<PR body>"
+   ```
+
+3. To update the pull request, push again with the same `topic`.

elydora/__init__.py

@@ -68,6 +68,7 @@ from .types import (
     AuthLoginResponse,
     GetMeResponse,
     IssueApiTokenResponse,
+    IssueTokenResponse,
     RotateApiTokenResponse,
     HealthResponse,
     DeepHealthResponse,
@@ -142,6 +143,7 @@ __all__ = [
     "AuthLoginResponse",
     "GetMeResponse",
     "IssueApiTokenResponse",
+    "IssueTokenResponse",
     "RotateApiTokenResponse",
     "HealthResponse",
     "DeepHealthResponse",

elydora/_version.py

@@ -1,3 +1,3 @@
 """Canonical Elydora package version."""
 
-__version__ = "2.1.0"
+__version__ = "2.1.1"

elydora/async_client.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import warnings
+from urllib.parse import quote
 from typing import Any, Dict, List, Optional, Union
 
 import aiohttp
@@ -130,9 +131,11 @@ class AsyncElydoraClient:
             headers=build_headers(self.token),
         )
 
-    async def _get_public(self, path: str) -> Any:
+    async def _get_public(self, path: str, *, accept_status: Optional[int] = None) -> Any:
         session = await self._get_session()
         async with session.get(f"{self.base_url}{path}", timeout=TIMEOUT) as response:
+            if accept_status is not None and response.status == accept_status:
+                return await response.json()
             return await self._handle_response(response)
 
     @staticmethod
@@ -193,6 +196,15 @@ class AsyncElydoraClient:
             "POST", "/v1/auth/token", json_body=api_token_body(ttl_seconds)
         )
 
+    async def issue_token(self, ttl_seconds: Optional[int] = None) -> IssueApiTokenResponse:
+        """Deprecated alias for issue_api_token()."""
+        warnings.warn(
+            "AsyncElydoraClient.issue_token() is deprecated. Use issue_api_token().",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return await self.issue_api_token(ttl_seconds=ttl_seconds)
+
     async def rotate_api_token(self) -> RotateApiTokenResponse:
         return await self._request("POST", "/v1/auth/rotate", json_body={})
 
@@ -201,19 +213,19 @@ class AsyncElydoraClient:
         return await self._request("POST", "/v1/agents/register", json_body=request)
 
     async def get_agent(self, agent_id: str) -> GetAgentResponse:
-        return await self._request("GET", f"/v1/agents/{agent_id}")
+        return await self._request("GET", f"/v1/agents/{quote(agent_id, safe='')}")
 
     async def list_agents(self) -> ListAgentsResponse:
         return await self._request("GET", "/v1/agents")
 
     async def freeze_agent(self, agent_id: str, reason: str) -> FreezeAgentResponse:
         return await self._request(
-            "POST", f"/v1/agents/{agent_id}/freeze", json_body={"reason": reason}
+            "POST", f"/v1/agents/{quote(agent_id, safe='')}/freeze", json_body={"reason": reason}
         )
 
     async def unfreeze_agent(self, agent_id: str, reason: str) -> UnfreezeAgentResponse:
         return await self._request(
-            "POST", f"/v1/agents/{agent_id}/unfreeze", json_body={"reason": reason}
+            "POST", f"/v1/agents/{quote(agent_id, safe='')}/unfreeze", json_body={"reason": reason}
         )
 
     async def update_agent(
@@ -221,15 +233,15 @@ class AsyncElydoraClient:
     ) -> UpdateAgentResponse:
         require_integration_type(integration_type)
         return await self._request(
-            "PATCH", f"/v1/agents/{agent_id}", json_body={"integration_type": integration_type}
+            "PATCH", f"/v1/agents/{quote(agent_id, safe='')}", json_body={"integration_type": integration_type}
         )
 
     async def delete_agent(self, agent_id: str) -> DeleteAgentResponse:
-        return await self._request("DELETE", f"/v1/agents/{agent_id}")
+        return await self._request("DELETE", f"/v1/agents/{quote(agent_id, safe='')}")
 
     async def revoke_key(self, agent_id: str, kid: str, reason: str) -> None:
         await self._request(
-            "POST", f"/v1/agents/{agent_id}/revoke", json_body={"kid": kid, "reason": reason}
+            "POST", f"/v1/agents/{quote(agent_id, safe='')}/revoke", json_body={"kid": kid, "reason": reason}
         )
 
     def create_operation(
@@ -349,4 +361,5 @@ class AsyncElydoraClient:
         return await self._get_public("/v1/health")
 
     async def deep_health(self) -> DeepHealthResponse:
-        return await self._get_public("/v1/health/deep")
+        """503 carries the degraded report, not an error."""
+        return await self._get_public("/v1/health/deep", accept_status=503)

elydora/client.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import warnings
+from urllib.parse import quote
 from typing import Any, Dict, List, Optional, Union
 
 import requests
@@ -119,8 +120,10 @@ class ElydoraClient:
             headers=build_headers(self.token),
         )
 
-    def _get_public(self, path: str) -> Any:
+    def _get_public(self, path: str, *, accept_status: Optional[int] = None) -> Any:
         response = self._session.get(f"{self.base_url}{path}", timeout=REQUEST_TIMEOUT_SECONDS)
+        if accept_status is not None and response.status_code == accept_status:
+            return response.json()
         return self._handle_response(response)
 
     @staticmethod
@@ -179,6 +182,15 @@ class ElydoraClient:
     def issue_api_token(self, ttl_seconds: Optional[int] = None) -> IssueApiTokenResponse:
         return self._request("POST", "/v1/auth/token", json_body=api_token_body(ttl_seconds))
 
+    def issue_token(self, ttl_seconds: Optional[int] = None) -> IssueApiTokenResponse:
+        """Deprecated alias for issue_api_token()."""
+        warnings.warn(
+            "ElydoraClient.issue_token() is deprecated. Use issue_api_token().",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.issue_api_token(ttl_seconds=ttl_seconds)
+
     def rotate_api_token(self) -> RotateApiTokenResponse:
         return self._request("POST", "/v1/auth/rotate", json_body={})
 
@@ -187,29 +199,29 @@ class ElydoraClient:
         return self._request("POST", "/v1/agents/register", json_body=request)
 
     def get_agent(self, agent_id: str) -> GetAgentResponse:
-        return self._request("GET", f"/v1/agents/{agent_id}")
+        return self._request("GET", f"/v1/agents/{quote(agent_id, safe='')}")
 
     def list_agents(self) -> ListAgentsResponse:
         return self._request("GET", "/v1/agents")
 
     def freeze_agent(self, agent_id: str, reason: str) -> FreezeAgentResponse:
-        return self._request("POST", f"/v1/agents/{agent_id}/freeze", json_body={"reason": reason})
+        return self._request("POST", f"/v1/agents/{quote(agent_id, safe='')}/freeze", json_body={"reason": reason})
 
     def unfreeze_agent(self, agent_id: str, reason: str) -> UnfreezeAgentResponse:
-        return self._request("POST", f"/v1/agents/{agent_id}/unfreeze", json_body={"reason": reason})
+        return self._request("POST", f"/v1/agents/{quote(agent_id, safe='')}/unfreeze", json_body={"reason": reason})
 
     def update_agent(self, agent_id: str, integration_type: IntegrationType) -> UpdateAgentResponse:
         require_integration_type(integration_type)
         return self._request(
-            "PATCH", f"/v1/agents/{agent_id}", json_body={"integration_type": integration_type}
+            "PATCH", f"/v1/agents/{quote(agent_id, safe='')}", json_body={"integration_type": integration_type}
         )
 
     def delete_agent(self, agent_id: str) -> DeleteAgentResponse:
-        return self._request("DELETE", f"/v1/agents/{agent_id}")
+        return self._request("DELETE", f"/v1/agents/{quote(agent_id, safe='')}")
 
     def revoke_key(self, agent_id: str, kid: str, reason: str) -> None:
         self._request(
-            "POST", f"/v1/agents/{agent_id}/revoke", json_body={"kid": kid, "reason": reason}
+            "POST", f"/v1/agents/{quote(agent_id, safe='')}/revoke", json_body={"kid": kid, "reason": reason}
         )
 
     def create_operation(
@@ -324,4 +336,5 @@ class ElydoraClient:
         return self._get_public("/v1/health")
 
     def deep_health(self) -> DeepHealthResponse:
-        return self._get_public("/v1/health/deep")
+        """503 carries the degraded report, not an error."""
+        return self._get_public("/v1/health/deep", accept_status=503)

elydora/types.py

@@ -351,10 +351,15 @@ class IssueApiTokenResponse(TypedDict):
     token_id: str
 
 
+# Deprecated alias for IssueApiTokenResponse.
+IssueTokenResponse = IssueApiTokenResponse
+
+
 class RotateApiTokenResponse(TypedDict):
     token: str
     expires_at: Optional[int]
     token_id: str
+    previous_token_grace_until: int
 
 
 class HealthResponse(TypedDict):